A local video studio for your coding agent. Describe a video in one sentence: your agent directs, your machine renders. Claude Code, Codex, Cursor, Devin and more. No API keys, no uploads.
Python agent-skillsai-agentscaptionsclaude-codeclaude-code-pluginclaude-skillscodexcursorexplainer-videoffmpegheadless-chromekokoro-ttslocal-firstmanimmcp-servermotion-graphicstext-to-speechvideovideo-editingvideo-generation
Site and docs: the footer and reference tables no longer scroll sideways, and two step-by-step tutorials (#81)
Favio Vázquez2122ca44520b
diff --git a/README.md b/README.mdindex f74d439..0911366 100644--- a/README.md+++ b/README.md@@ -1710,7 +1710,7 @@ language, a CPU limit) and the render progress monitor.<img alt="The documentation map: eighteen workflows (launch video, explainer, tutorial, social short, data story, footage edit, trailer, slideshow, changelog video, music video, voice-over only, localize, repo explainer, paper explainer, repro, diagram, recap, x-ray), then five acts and a finale of guides, from onboarding to qa and review." src="assets/readme/diagrams/docs-map-light.svg" width="100%"></picture></p>-For people: [fifteen task guides](docs/guides/README.md) (what to say to your agent, what it runs, what you get, how+For people: [sixteen task guides](docs/guides/README.md) (what to say to your agent, what it runs, what you get, howlong it takes), [What's new](docs/whats-new.md) (each release in one sentence a feature) and the [FAQ](docs/faq.md)(GPUs, cost, agents, privacy, licences, disk, time, platforms, languages).diff --git a/assets/readme/tutorials/first-video/01-terminal-job.webp b/assets/readme/tutorials/first-video/01-terminal-job.webpnew file mode 100644index 0000000..497f435Binary files /dev/null and b/assets/readme/tutorials/first-video/01-terminal-job.webp differdiff --git a/assets/readme/tutorials/first-video/02-terminal-check.webp b/assets/readme/tutorials/first-video/02-terminal-check.webpnew file mode 100644index 0000000..a1c06b4Binary files /dev/null and b/assets/readme/tutorials/first-video/02-terminal-check.webp differdiff --git a/assets/readme/tutorials/first-video/03-look.webp b/assets/readme/tutorials/first-video/03-look.webpnew file mode 100644index 0000000..737233fBinary files /dev/null and b/assets/readme/tutorials/first-video/03-look.webp differdiff --git a/assets/readme/tutorials/first-video/04-terminal-render-qa.webp b/assets/readme/tutorials/first-video/04-terminal-render-qa.webpnew file mode 100644index 0000000..5a4bd11Binary files /dev/null and b/assets/readme/tutorials/first-video/04-terminal-render-qa.webp differdiff --git a/assets/readme/tutorials/first-video/05-fix-and-pass.webp b/assets/readme/tutorials/first-video/05-fix-and-pass.webpnew file mode 100644index 0000000..01743adBinary files /dev/null and b/assets/readme/tutorials/first-video/05-fix-and-pass.webp differdiff --git a/assets/readme/tutorials/first-video/06-final.webp b/assets/readme/tutorials/first-video/06-final.webpnew file mode 100644index 0000000..27e4bc3Binary files /dev/null and b/assets/readme/tutorials/first-video/06-final.webp differdiff --git a/assets/readme/tutorials/first-video/07-terminal-review-pack.webp b/assets/readme/tutorials/first-video/07-terminal-review-pack.webpnew file mode 100644index 0000000..6123395Binary files /dev/null and b/assets/readme/tutorials/first-video/07-terminal-review-pack.webp differdiff --git a/assets/readme/tutorials/first-video/08-review-sheet.webp b/assets/readme/tutorials/first-video/08-review-sheet.webpnew file mode 100644index 0000000..6a53a14Binary files /dev/null and b/assets/readme/tutorials/first-video/08-review-sheet.webp differdiff --git a/assets/readme/tutorials/first-video/09-findings.webp b/assets/readme/tutorials/first-video/09-findings.webpnew file mode 100644index 0000000..9bbd3acBinary files /dev/null and b/assets/readme/tutorials/first-video/09-findings.webp differdiff --git a/assets/readme/tutorials/first-video/10-terminal-waive.webp b/assets/readme/tutorials/first-video/10-terminal-waive.webpnew file mode 100644index 0000000..9707879Binary files /dev/null and b/assets/readme/tutorials/first-video/10-terminal-waive.webp differdiff --git a/assets/readme/tutorials/first-video/11-receipt.webp b/assets/readme/tutorials/first-video/11-receipt.webpnew file mode 100644index 0000000..b6bf058Binary files /dev/null and b/assets/readme/tutorials/first-video/11-receipt.webp differdiff --git a/assets/readme/tutorials/first-video/clip.webp b/assets/readme/tutorials/first-video/clip.webpnew file mode 100644index 0000000..75acd1eBinary files /dev/null and b/assets/readme/tutorials/first-video/clip.webp differdiff --git a/assets/readme/tutorials/studio/01-terminal-board.webp b/assets/readme/tutorials/studio/01-terminal-board.webpnew file mode 100644index 0000000..a96c4e7Binary files /dev/null and b/assets/readme/tutorials/studio/01-terminal-board.webp differdiff --git a/assets/readme/tutorials/studio/02-board.webp b/assets/readme/tutorials/studio/02-board.webpnew file mode 100644index 0000000..120a7e7Binary files /dev/null and b/assets/readme/tutorials/studio/02-board.webp differdiff --git a/assets/readme/tutorials/studio/03-compare.webp b/assets/readme/tutorials/studio/03-compare.webpnew file mode 100644index 0000000..d4906b3Binary files /dev/null and b/assets/readme/tutorials/studio/03-compare.webp differdiff --git a/assets/readme/tutorials/studio/04-comment.webp b/assets/readme/tutorials/studio/04-comment.webpnew file mode 100644index 0000000..3c8b28fBinary files /dev/null and b/assets/readme/tutorials/studio/04-comment.webp differdiff --git a/assets/readme/tutorials/studio/05-feedback.webp b/assets/readme/tutorials/studio/05-feedback.webpnew file mode 100644index 0000000..b7439a1Binary files /dev/null and b/assets/readme/tutorials/studio/05-feedback.webp differdiff --git a/assets/readme/tutorials/studio/06-terminal-digest.webp b/assets/readme/tutorials/studio/06-terminal-digest.webpnew file mode 100644index 0000000..6f51d2eBinary files /dev/null and b/assets/readme/tutorials/studio/06-terminal-digest.webp differdiff --git a/assets/readme/tutorials/studio/07-storyboard.webp b/assets/readme/tutorials/studio/07-storyboard.webpnew file mode 100644index 0000000..2bb6902Binary files /dev/null and b/assets/readme/tutorials/studio/07-storyboard.webp differdiff --git a/assets/readme/tutorials/studio/08-shot-note.webp b/assets/readme/tutorials/studio/08-shot-note.webpnew file mode 100644index 0000000..909827fBinary files /dev/null and b/assets/readme/tutorials/studio/08-shot-note.webp differdiff --git a/assets/readme/tutorials/studio/09-approve.webp b/assets/readme/tutorials/studio/09-approve.webpnew file mode 100644index 0000000..a0d60f9Binary files /dev/null and b/assets/readme/tutorials/studio/09-approve.webp differdiff --git a/assets/readme/tutorials/studio/10-terminal-storyboard.webp b/assets/readme/tutorials/studio/10-terminal-storyboard.webpnew file mode 100644index 0000000..3d997d6Binary files /dev/null and b/assets/readme/tutorials/studio/10-terminal-storyboard.webp differdiff --git a/assets/readme/tutorials/studio/11-final.webp b/assets/readme/tutorials/studio/11-final.webpnew file mode 100644index 0000000..c17ffb8Binary files /dev/null and b/assets/readme/tutorials/studio/11-final.webp differdiff --git a/assets/readme/tutorials/studio/clip.webp b/assets/readme/tutorials/studio/clip.webpnew file mode 100644index 0000000..09bcfdeBinary files /dev/null and b/assets/readme/tutorials/studio/clip.webp differdiff --git a/docs/README.md b/docs/README.mdindex 217bef3..a928adb 100644--- a/docs/README.md+++ b/docs/README.md@@ -46,6 +46,7 @@ Written for people rather than for your agent:| Page | Read it when ||---|---|| [Your first video](guides/first-video.md) | you are new: a 5-second test video and what each step does |+| [Studio, step by step](guides/studio-concepts-to-final.md) | you want options first: one real run from concepts to the final film, a screenshot at each step || [Task guides](guides/README.md) | you want a recipe: what to say, what your agent runs, what you get, how long it takes || [What's new](whats-new.md) | you want each release's new features, one sentence each || [Questions people ask](faq.md) | you want short answers: GPU, cost, agents, privacy, licences, disk, time, platforms, languages |diff --git a/docs/guides/README.md b/docs/guides/README.mdindex edf1a86..6305563 100644--- a/docs/guides/README.md+++ b/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. 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 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.| Guide | When you want ||---|---|@@ -16,6 +16,7 @@ look at. The references in `skills/showtime/references/` are written for your ag| [Make a short film of what your agent did](session-recap.md) | a 30-60 s recap of a Claude Code session for a PR, a standup or a post, from allow-listed facts only || [Turn a failing test into a bug-report video](bug-report-video.md) | a failing Playwright test as a narrated video and a summary to paste into the issue || [Make an X-ray of a real thing](xray.md) | a clip of a machine or an instrument with its inside drawn moving on the exact frames its sound says, its music as a score, tab or drum sheet, and a receipt that proves it |+| [Studio: from concepts to the final film](studio-concepts-to-final.md) | open the studio board, compare concepts, leave notes, approve a storyboard and see the final, one real run in eight steps || [Make a living diagram, and a live figure](living-diagram.md) | how something works, as a figure that builds itself, and a live figure people hover, step through and tune || [Make an explainer that stops and asks](explainer-that-asks.md) | questions the web version stops on, links to a moment or a stretch, link previews || [Go all out: a showreel](go-all-out.md) | a hype reel with flash words, a shutter blur on snaps, and WebGL looks |diff --git a/docs/guides/first-video.md b/docs/guides/first-video.mdindex ac3ec75..926195f 100644--- a/docs/guides/first-video.md+++ b/docs/guides/first-video.md@@ -1,8 +1,12 @@# Make your first video+<!-- tutorial: numbered steps, each with a screenshot from one real run -->+Start here if you have never used showtime. Ask for a 5-second test video: your agent installs what is missing, makes-the video on your computer and checks it. You learn that the install works, and you see every step a bigger video-goes through.+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.++## Say this@@ -13,44 +17,107 @@ them with `uv --version` and `node --version`, and restart your coding agent. Ad> "Make a 5-second test video that says hello."-## What happens--1. **One line of assumptions,** before anything runs: "Quick mode: 5 s, 16:9, no voice-over; full review, say 'lean'- for a draft pass." It asks a question only when a request could mean two different videos.-2. **Setup, the first time only.** `showtime job init` stops with "setup has not been run yet". Your agent tells you- the download (about 0.5 to 0.75 GB, usually 2 to 6 minutes; `showtime setup --estimate` prints yours) and runs- `showtime setup` once you say yes. A sandbox blocks it? See- [Troubleshooting](../troubleshooting.md#setup-never-ran-or-the-sandbox-blocked-it).-3. **A job folder.** `showtime job init hello` makes `showtime-out/hello-<date>-<time>/` for everything this request- makes ([what is in it](../glossary.md#the-job-folder)).-4. **A first look.** `showtime new dom <job>/project --duration 5` copies a starter page, fits it to 5 s and dresses- it in a [look signature](../glossary.md#look-signature). Your agent writes "hello" into it, runs `showtime check`- and `showtime look`, and shows you a still or a fast draft.-5. **The render.** `showtime render <job>/project --job <job>` draws every frame in a headless browser on your- computer. Nothing is uploaded.-6. **The checks.** `showtime qa <job>` checks the file, the loudness, black or frozen stretches and the poster, and- prints PASS, WARN or FAIL. In quality mode (the default) a [critic](../glossary.md#critic) then reviews the video;- until it has, qa says "review pending".-7. **The delivery card:** the files, the length, the loudness, the qa verdict, the review, what was assumed, and- three things you could ask for next.--## What you get--- `final.mp4` (1920x1080, 30 fps) and `poster.jpg`. Open `final.mp4`: that is your first video.-- `receipt.md`: the request as you typed it, the renders, the time, and the tokens and cost when your agent reports- them. `share.txt` holds the receipt's one line.-- `project/`: the page your agent wrote. Edit it and ask for a new render; renders never overwrite.+Your agent writes one line of assumptions before anything runs ("Quick mode: 5 s, 16:9, no voice-over; full review,+say 'lean' for a draft pass"). It asks a question only when a request could mean two different videos.++## 1. Setup and a job folder++The first time only, `showtime job init` stops with "setup has not been run yet". Your agent tells you the download+(about 0.5 to 0.75 GB, usually 2 to 6 minutes; `showtime setup --estimate` prints yours) and runs `showtime setup` once+you say yes. A sandbox blocks it? See [Troubleshooting](../troubleshooting.md#setup-never-ran-or-the-sandbox-blocked-it).++Then the job: a folder, `showtime-out/hello-<date>-<time>/`, for everything this request makes+([what is in it](../glossary.md#the-job-folder)). `showtime new dom` copies a starter page into it, fits it to 5 s and+dresses it in a [look signature](../glossary.md#look-signature).++The terminal output in the pictures is trimmed to the lines that matter.++++## 2. Your agent writes "hello" and checks the page++Your agent writes the word into the page, `showtime check` tests it before any render (fonts, contrast, text layout,+that nothing moves by chance), and `showtime look` makes one small image of the key frames.++++The look image is the first thing you can judge: three frames of the page, with nothing rendered yet.++++## 3. The first render, and what qa says++`showtime render` draws every frame in a headless browser on your computer. Nothing is uploaded. Then `showtime qa`+checks the file itself: the codec, black or frozen stretches, the poster, the loudness, and what the project says to+expect. Here it warns that the last 4.1 seconds are a still hold.++++## 4. Fix it and render again++Renders never overwrite, so the fixed renders are `final-2.mp4` and `final-3.mp4`. Your agent made two changes:+a slow drift on the glow so the end is not frozen, and a line in `showtime.json` that says this film is meant to be+silent, so qa does not ask for music. The fixed file passes.++++## 5. Open the video++`final-3.mp4` (1920x1080, 30 fps) and its poster are in the job folder. Open the file: that is your first video. The+frames below are from the run itself.++++## 6. A critic reviews it++In quality mode (the default) the finished video is reviewed before it counts as done. `showtime review-pack` makes+a pack of contact sheets, key frames and the qa result, and a second agent, which sees only that pack, writes its+findings.++++++## 7. Read the findings and answer each one++The verdict here was "ship after fixes": no blockers, four should-fix points and three polish notes. Every finding is+fixed or waived with a reason. Blocker and should-fix findings hold the delivery until they are answered (until the+critic's verdict is in, `showtime qa` and the delivery say "review pending"); polish notes never do. For this test+card all seven were waived, and the reasons are in the receipt:++- a one-frame pop at the start: the first frame is also the poster, on purpose;+- a glow that stops short of the right and bottom edges: the strip is faint on a test card;+- a small line of text: this card is not for a phone feed;+- a 3.6 s still stretch: five seconds is the ask;+- the three polish notes (timing of the fade, the three parts arriving one after another, no brand on the card): not+ needed for a test.++On a real video you would fix the should-fix points and render again; the [review and notes guide](notes-and-fixes.md)+shows that.++++++## 8. The receipt++`showtime receipt` writes `receipt.md`: the request as you typed it, the review rounds and what became of each+finding, the renders, the time, and the tokens and cost when your agent reports them. `share.txt` holds one line of it.+The delivery card your agent shows you has the same facts and three things you could ask for next.++## How long it takes-Measured for this guide on a 6-core Intel Mac with its GPU, while other jobs kept it busy (load average about 4):+Measured for this guide on a 6-core Intel Mac (i5-8500), with other jobs running (load average about 3):| Step | Command | Time ||---|---|---|-| Make the job and check setup | `showtime job init hello --request "..."` | 0.8 to 15 s (two runs) |-| Copy and fit the starter page | `showtime new dom <job>/project --duration 5` | 3 s |-| Render 5 s at 1080p (3 browsers) | `showtime render <job>/project --job <job>` | 78 s |-| Check the file | `showtime qa <job>` | 10 s |+| Make the job and check setup | `showtime job init hello --request "..."` | 6.7 s |+| Copy and fit the starter page | `showtime new dom <job>/project --duration 5` | 0.8 s |+| Check the page | `showtime check <job>/project` | 17.3 s |+| Render 5 s at 1080p | `showtime render <job>/project --job <job>` | 6.5 s (3.9 s capture, 2.6 s encode) |+| Check the file | `showtime qa <job>` | 1.2 to 2.5 s |Setup comes first, the first time (usually 2 to 6 minutes). Your agent's writing and the critic's review come ontop and were not timed. More numbers: [render § Speed](../../skills/showtime/references/render.md#speed).@@ -68,7 +135,9 @@ top and were not timed. More numbers: [render § Speed](../../skills/showtime/rea brief, footage.- Setup needs the network once. Bigger pieces (the transcription model, Manim, music tracks) download the first timea video needs them, with their size shown first. The test video downloads nothing more.-- Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).+- 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).## The examplediff --git a/docs/guides/studio-concepts-to-final.md b/docs/guides/studio-concepts-to-final.mdnew file mode 100644index 0000000..96b126e--- /dev/null+++ b/docs/guides/studio-concepts-to-final.md@@ -0,0 +1,126 @@+# Studio: from concepts to the final film++<!-- tutorial: numbered steps, each with a screenshot from one real run -->++Studio mode opens a local board where you choose a concept, compare it with the others, leave notes, approve a+storyboard, and only then does the film get built. This guide walks through one real run, step by step, with a+screenshot of each step. The video is a 20-second trailer for Tidepool, a fictional notes app that ships with showtime+as sample material.++++## Say this++> "Show me options first for a 20-second trailer that tells note-takers everything they write stays on their own+> machine."++"Options first" (or "studio") is the trigger. Without it, your agent goes straight to a draft.++## 1. Your agent starts the session and builds the board++It makes a job, attaches a studio session to it, writes the concepts into `studio/board.json`, and renders one to+three style frames for each concept. Then it checks the board and opens it.++++The terminal output is trimmed to the lines that matter; `showtime studio frame` runs once per concept. The link is+local (`127.0.0.1`) and carries a key. It opens nowhere else.++## 2. Open the board++Round 1 is the question "which direction feels like a Tidepool trailer?". There are three concepts and one wildcard.+Each card has its frames, a one-line pitch, the hook of the first three seconds, a palette, type, music and the risk.+One concept is marked **Recommended**, with the reason.++++## 3. Compare two concepts++The **Compare** tab puts any two concepts on one frame. Drag across it to wipe from one to the other.++++## 4. Pick, like and comment++**Pick** chooses a concept. The heart likes one, and you can like a concept you did not pick, to say "keep this part".+The speech-bubble button opens a comment. Here the reviewer picks C2, likes C1 and writes that the film should land on+C1's sunrise.++++Every click is saved on your computer in `studio/feedback.json`. Press **Feedback** to read what you left:++++## 5. Your agent reads it and answers++You tell your agent you are done. It runs `showtime studio feedback`, repeats what you said in a few lines, logs the+decision in `decisions.md` (append-only) and brings out the next round. What you typed on the board is quoted as+your opinion about the video; it is never run as an instruction.++++## 6. Check the storyboard++Round 2 is the storyboard of the concept you picked: every shot with its time range, what is on screen, and a note on+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 **Animatic** below the storyboard is a rough cut with the music, to judge pace before anything is rendered;+`n` adds a note at the moment you are watching.++## 7. Approve++The **Decide** tab has the questions your agent still needs answered, two dials (energy and pace) and an **Approve**+button for the concept you want built, with a box for final notes.++++Your agent reads the approval, logs it and builds the film. This is the last point to change your mind cheaply.++++## 8. See the final++`showtime render` draws every frame on your computer, and `showtime qa` checks the file. For this film the render took+45 seconds for 20 seconds of 1080p.++++In quality mode (the default), a critic reviews the finished film and you can leave notes on it too:+[Leave notes on a video and get them fixed](notes-and-fixes.md). The finished trailer from an earlier run of this+same session is [example 09](https://github.com/FavioVazquez/showtime-examples/blob/main/examples/09-studio-trailer/README.md).++## How long it takes++Measured for this guide on a 6-core Intel Mac (i5-8500), while nothing else was rendering:++| Step | What ran | Time |+|---|---|---|+| Style frames, one concept | `showtime studio frame ... --html` (3 frames) | 2.8 to 3.2 s (39 s the first time, while the browser started) |+| Storyboard thumbnails | `showtime studio frame ... --project --at` (8 frames) | 9.6 s |+| The final render | `showtime render <project> --job <job>` (20 s, 1080p) | 45 s |++Your agent's writing of the concepts and your own time on the board come on top and were not timed.++## Phrases that change it++- "Show me options first", "studio", "I want control": opens the board.+- "Only stop me for concepts": your agent fills the other stops with its recommended answer and logs them as assumed.+- "Resume the studio": it reads `brief.md` and `decisions.md` and carries on; it never asks a settled question again.+- "Export the board": `showtime studio export <job> --inline` makes one HTML file you can send.++## Limits++- The board is local. Anyone you send the link to cannot open it; export it if someone else must look.+- The style frames show a direction, not the film. A concept can look right in frames and still be hard to animate.+- 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.+- The commands behind each step: [Studio mode](../../skills/showtime/references/studio.md); the board file:+ [Board format](../../skills/showtime/references/boards.md).diff --git a/site/build.py b/site/build.pyindex f74905e..040eda7 100644--- a/site/build.py+++ b/site/build.py@@ -493,9 +493,27 @@ class Site: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 = mark_url_links(body)+ body = keep_flags_whole(body)return body, title, heads+def mark_url_links(body: str) -> str:+ """A link whose text looks like an address (a source or a credit) gets class="url", so it may break anywhere and+ never widens the page; links with words as their text keep wrapping at spaces, and a link that already has a+ class attribute is left alone."""+ return re.sub(r'<a(?![^>]*\sclass=) ([^>]*href="https?://[^"]*"[^>]*)>(https?://[^<]*)</a>', r'<a class="url" \1>\2</a>', body)+++def keep_flags_whole(body: str) -> str:+ """In a table cell, a command-line flag (--check, -x) is wrapped in a nowrap span so a narrow column breaks the+ line before it, never after its dashes; the copied text does not change."""+ flag = re.compile(r'(?<![\w-])(--?[A-Za-z0-9][\w-]*)')+ code = re.compile(r'<code>([^<]*)</code>')+ cell = re.compile(r'<td\b[^>]*>.*?</td>', re.S)+ return cell.sub(lambda c: code.sub(lambda m: '<code>%s</code>' % flag.sub(r'<span class="nb">\1</span>', m.group(1)), c.group(0)), body)++# ----------------------------------------------------------------------------------------------- the shellICON_SUN = ('<svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true">'diff --git a/site/static/style.css b/site/static/style.cssindex 45b768d..f99c8a9 100644--- a/site/static/style.css+++ b/site/static/style.css@@ -257,8 +257,11 @@ p{margin:0}.prose h2:hover .anchor,.prose h3:hover .anchor,.prose .anchor:focus{opacity:1}.prose table{display:block;overflow-x:auto;border-collapse:collapse;font-size:.92rem;line-height:1.5;margin:1.6em 0;max-width:100%}.prose th,.prose td{text-align:left;vertical-align:top;padding:10px 20px 10px 0;border-bottom:1px solid var(--line)}-.prose th{font-weight:600;color:var(--ink);border-bottom-color:var(--line-2);white-space:nowrap}-.prose td code{white-space:nowrap}+.prose th{font-weight:600;color:var(--ink);border-bottom-color:var(--line-2)}+.prose td code .nb{white-space:nowrap} /* a --flag never breaks after its dashes */+.prose td code{overflow-wrap:break-word} /* wraps at spaces; a long unbroken token is the only thing that may push the table wider */+.prose a.url{overflow-wrap:anywhere}+.prose li,.prose p{overflow-wrap:break-word} /* a credit's file name or bare URL longer than the screen breaks instead of scrolling the page */.prose td pre{white-space:pre-wrap;font-size:.72rem;padding:10px 12px;margin:10px 0 8px}.prose td pre code{white-space:inherit}/* the docs map's Overture (three steps, one with the install block): one step under another on a phone */@@ -306,7 +309,7 @@ p{margin:0}footer.site{border-top:1px solid var(--line);padding:40px 0 56px;color:var(--muted);font-size:.88rem}footer.site .wrap{display:flex;flex-wrap:wrap;gap:12px 32px;align-items:baseline;justify-content:space-between;max-width:1360px}-footer.site nav{display:flex;gap:20px}+footer.site nav{display:flex;flex-wrap:wrap;gap:8px 20px}footer.site a{color:var(--muted);text-decoration:none}footer.site a:hover{color:var(--ink)}footer.site .word{font-family:var(--serif);font-weight:900;color:var(--ink);font-size:1.05rem;font-variation-settings:"opsz" 144}diff --git a/skills/showtime/references/studio.md b/skills/showtime/references/studio.mdindex ea1c182..b338644 100644--- a/skills/showtime/references/studio.md+++ b/skills/showtime/references/studio.md@@ -7,7 +7,7 @@ before asking the first studio question. The board format is in `boards.md`.Quick mode stays the default: one request in, a video out. Studio is opt-in. In studio you **talkabout facts and goals, and show anything about look, sound or timing** as a board: a local page withlettered options, one recommendation, and buttons the user clicks. Chat stays the source of truth;-the board is a faster way to answer.+the board is a faster way to answer. For people: [see it step by step](https://faviovazquez.github.io/showtime/docs/guides/studio-concepts-to-final.html), one real run with a screenshot of each step.## Essentialsdiff --git a/skills/showtime/tests/test_site_build.py b/skills/showtime/tests/test_site_build.pyindex 1368d9d..b8de64c 100644--- a/skills/showtime/tests/test_site_build.py+++ b/skills/showtime/tests/test_site_build.py@@ -208,6 +208,76 @@ class OneVersion(unittest.TestCase):self.assertEqual(build.latest_release(limit=1, text=notes, version="0.4.1"), ("0.4.1", "One; and more."))self.assertEqual(build.latest_release(text="# nothing\n", version="0.4.1"), ("0.4.1", "See what changed."))+ def test_footer_nav_wraps_on_a_phone(self):+ # the public build adds the examples-repo link to the footer nav; without flex-wrap the row grew 3 px past a+ # 375 px screen (a sideways scroll on every page). The row must be allowed to wrap.+ css = (REPO / "site" / "static" / "style.css").read_text(encoding="utf-8")+ rule = re.search(r"footer\.site nav\{([^}]*)\}", css)+ self.assertIsNotNone(rule)+ self.assertIn("flex-wrap:wrap", rule.group(1))++ def test_table_cells_wrap_at_spaces(self):+ # a long command in a reference table (studio Commands) must wrap in its cell: with nowrap the table grew past+ # its column (920 px in 704), the first column took 758 px and the rows stood 150 px tall+ css = (REPO / "site" / "static" / "style.css").read_text(encoding="utf-8")+ for sel in (r"\.prose th", r"\.prose td code"):+ rule = re.search(sel + r"\{([^}]*)\}", css)+ self.assertIsNotNone(rule, sel)+ self.assertNotIn("nowrap", rule.group(1), sel)+ # break at spaces first; a mid-word break is only for the one token that is longer than the cell+ self.assertIn("overflow-wrap:break-word", re.search(r"\.prose td code\{([^}]*)\}", css).group(1))++ def test_address_links_may_break_anywhere(self):+ # sources and credits print their URLs as link text; those links wrap, links with words do not change+ css = (REPO / "site" / "static" / "style.css").read_text(encoding="utf-8")+ self.assertIn("overflow-wrap:anywhere", re.search(r"\.prose a\.url\{([^}]*)\}", css).group(1))+ self.assertIn("overflow-wrap:break-word", re.search(r"\.prose li,\.prose p\{([^}]*)\}", css).group(1)) # bare URLs and file names in credits+ url = "https://www.eia.gov/totalenergy/data/browser/index.php?tbl=T07.02A"+ out = build.mark_url_links('<li><a href="%s">%s</a> and <a href="%s">the table</a> <a class="x" href="%s">%s</a></li>'+ % (url, url, url, url, url))+ self.assertEqual(out.count('class="url"'), 1)+ self.assertIn('<a class="url" href="%s">%s</a>' % (url, url), out)+ self.assertIn('<a href="%s">the table</a>' % url, out)+ self.assertIn('<a class="x" href="%s">' % url, out)++ def test_render_md_marks_address_links_and_keeps_flags_whole(self):+ # through the real renderer, not the helpers: deleting the calls in render_md must fail here+ site = build.Site(Path(tempfile.mkdtemp(prefix="st-md-")), [], "o/r", None, "main")+ md = ("# T\n\nSource: <https://www.eia.gov/totalenergy/data/browser/index.php?tbl=T07.02A> and "+ "[the table](https://www.eia.gov/totalenergy/).\n\n| Command | Use |\n|---|---|\n"+ "| `showtime check --strict -x file` | checks |\n")+ html, _t, _h = site.render_md(md, build.GUIDES / "x.md", "docs/guides/x.html")+ self.assertEqual(html.count('class="url"'), 1)+ self.assertIn('>the table</a>', html)+ self.assertIn('<span class="nb">--strict</span>', html)+ self.assertIn('<span class="nb">-x</span>', html)+ self.assertIn("showtime check --strict -x file", re.sub(r"<[^>]+>", "", html))+ self.assertNotIn("nb", build.keep_flags_whole("<p><code>--a</code></p>")) # only inside table cells++ def test_tutorials_have_a_picture_for_every_step(self):+ # a tutorial is a walk through one run: every numbered step has a picture with real alt text, no file is+ # missing, the clip at the top stays small, and nothing on the page names a private folder+ guides = [p for p in sorted((REPO / "docs" / "guides").glob("*.md")) if "<!-- tutorial:" in p.read_text(encoding="utf-8")]+ self.assertTrue(guides)+ for guide in guides:+ text = guide.read_text(encoding="utf-8")+ pics = re.findall(r"!\[([^\]]*)\]\(([^)]+)\)", text)+ self.assertGreaterEqual(len(pics), 10, guide.name)+ for alt, src in pics:+ self.assertGreater(len(alt), 20, src)+ self.assertTrue((guide.parent / src).is_file(), src)+ clip = [src for _a, src in pics if src.endswith("clip.webp")]+ self.assertEqual(len(clip), 1, guide.name)+ self.assertLess((guide.parent / clip[0]).stat().st_size, 3 * 1024 * 1024)+ for marker in ("/Users/", "/home/", "C:\\Users\\", "~/Projects"):+ self.assertNotIn(marker, text, guide.name)+ sections = re.split(r"^## ", text, flags=re.M)[1:]+ steps = [sec for sec in sections if re.match(r"\d+\. ", sec)]+ self.assertGreaterEqual(len(steps), 5, guide.name)+ for sec in steps:+ self.assertRegex(sec, r"!\[[^\]]{20,}\]\(", "%s: step '%s' has no picture" % (guide.name, sec.splitlines()[0]))+ self.assertIn("(%s)" % guide.name, (guide.parent / "README.md").read_text(encoding="utf-8") if guide.name != "first-video.md" else "(first-video.md)")+def test_landing_anchors_are_of_open_sections(self):# a heading is linked to the section it is in, never to one that closed before itout = Path(tempfile.mkdtemp(prefix="st-anchor-"))@@ -601,9 +671,19 @@ class Guides(unittest.TestCase):for p in self.guides():text = p.read_text(encoding="utf-8")n = len(text.rstrip("\n").splitlines())- self.assertTrue(50 <= n <= 90, "%s: %d lines (50-90)" % (p.name, n))heads = re.findall(r"^## (.+)$", text, re.M)- self.assertEqual([h for h in heads if h in GUIDE_SECTIONS], GUIDE_SECTIONS, p.name)+ if "<!-- tutorial:" in text:+ # a tutorial is a walk through one real run: numbered steps with a picture each, then the same closing sections+ self.assertTrue(60 <= n <= 160, "%s: %d lines (60-160)" % (p.name, n))+ steps = [h for h in heads if re.match(r"\d+\. ", h)]+ self.assertGreaterEqual(len(steps), 5, p.name)+ self.assertEqual([int(h.split(".")[0]) for h in steps], list(range(1, len(steps) + 1)), p.name)+ self.assertEqual([h for h in heads if h in GUIDE_SECTIONS[3:6] or h == "Say this"],+ ["Say this"] + GUIDE_SECTIONS[3:6], p.name)+ self.assertGreaterEqual(len(re.findall(r"^!\[[^\]]{20,}\]\(", text, re.M)), len(steps), p.name)+ else:+ self.assertTrue(50 <= n <= 90, "%s: %d lines (50-90)" % (p.name, n))+ self.assertEqual([h for h in heads if h in GUIDE_SECTIONS], GUIDE_SECTIONS, p.name)self.assertRegex(text, r"(example|examples)/|<!-- example: \d\d -->", p.name)@unittest.skipUnless(HAVE_EXAMPLES, NO_EXAMPLES)