Merge pull request #470 from posit-dev/feat-termshow-bundle

feat: add a single-file bundle format for Termshow recordings

Author: rich-iannone

README.md

@@ -144,7 +144,7 @@ If your package ships an [MCP](https://modelcontextprotocol.io/) server, Great D
 
 ### Terminal Recordings
 
-Teach your CLI visually with Termshow: record terminal sessions (by hand, or from a list of steps that `termshow check` can re-run in CI to catch demos that have gone out of date), edit them in a browser-based visual editor, and embed the results as animated SVG players in your documentation. Recordings are lightweight, theme-aware, and play inline without JavaScript dependencies. It's incredibly useful in onboarding guides, tutorials, and landing pages. If you already have VHS tapes, `great-docs termshow import-tape` turns them into Termshow scripts. For places that can't run the player, such as a GitHub README, `great-docs termshow export` writes the recording as a single animated SVG, with light and dark versions if you want them; `--gif`, `--mp4`, and `--webm` make a GIF or a video for pull requests, chat, and slides (with `ffmpeg`), `--cast` writes an asciicast file for asciinema, and `termshow snap` takes a still SVG or PNG of any moment. Every embedded recording carries a transcript of its text for screen readers and the page's Markdown version, and `termshow transcript` prints it, or the annotations and chapters as WebVTT. The player can be used from the keyboard and with a screen reader, and readers who ask for reduced motion get a still poster that steps through chapter by chapter. On sites built without Quarto, a `<termshow-player>` element plays recordings on any HTML page.
+Teach your CLI visually with Termshow: record terminal sessions (by hand, or from a list of steps that `termshow check` can re-run in CI to catch demos that have gone out of date), edit them in a browser-based visual editor, and embed the results as animated SVG players in your documentation. Recordings are lightweight, theme-aware, and play inline without JavaScript dependencies. It's incredibly useful in onboarding guides, tutorials, and landing pages. If you already have VHS tapes, `great-docs termshow import-tape` turns them into Termshow scripts. For places that can't run the player, such as a GitHub README, `great-docs termshow export` writes the recording as a single animated SVG, with light and dark versions if you want them; `--gif`, `--mp4`, and `--webm` make a GIF or a video for pull requests, chat, and slides (with `ffmpeg`), `--cast` writes an asciicast file for asciinema, `--bundle` puts a recording for the player in one `.termshow.json` file, and `termshow snap` takes a still SVG or PNG of any moment. Every embedded recording carries a transcript of its text for screen readers and the page's Markdown version, and `termshow transcript` prints it, or the annotations and chapters as WebVTT. The player can be used from the keyboard and with a screen reader, and readers who ask for reduced motion get a still poster that steps through chapter by chapter. On sites built without Quarto, a `<termshow-player>` element plays recordings on any HTML page.
 
 ### Lightbox
 
@@ -270,7 +270,7 @@ A persistent dark mode toggle with flash-free loading. Your users' preference is
 
 - Color swatches (inline and grid)
 - Lightbox (zoom, galleries, annotations, before/after compare)
-- Terminal recordings (record, edit, embed, export as animated SVG, GIF, MP4, WebM, or asciicast, screenshot, transcripts)
+- Terminal recordings (record, edit, embed, export as animated SVG, GIF, MP4, WebM, asciicast, or a single-file bundle, screenshot, transcripts)
 - Collapsible details sections
 - Keyboard keys styling
 - Horizontal rules with accent colors
@@ -409,7 +409,7 @@ Beyond `init`, `build`, and `preview`, Great Docs includes a full suite of quali
 | `great-docs termshow edit` | Open the browser-based visual editor for a recording |
 | `great-docs termshow play` | Preview a recording in the terminal |
 | `great-docs termshow render` | Render SVG frames without a full site build |
-| `great-docs termshow export` | Export a recording as one animated SVG for READMEs, as a GIF or video (`--gif`, `--mp4`, `--webm`), or as asciicast (`--cast`) |
+| `great-docs termshow export` | Export a recording as one animated SVG for READMEs, as a GIF or video (`--gif`, `--mp4`, `--webm`), as asciicast (`--cast`), or as a single-file bundle for the player (`--bundle`) |
 | `great-docs termshow snap` | Take a still SVG or PNG of one moment in a recording |
 | `great-docs termshow transcript` | Print a recording's text as Markdown, or its annotations or chapters as WebVTT |
 | `great-docs termshow validate` | Check a recording and its script for mistakes |

docs/user_guide/41-terminal-recordings.qmd

@@ -1601,6 +1601,30 @@ left out, and the command lists any the script has. Pass `--no-script` to export
 exactly as it was recorded. The SVG options (`--chapter-cards`, `--no-loop`, and so on) don't apply
 here.
 
+## Exporting a Bundle
+
+`termshow render` writes a directory of files for the player. A bundle has everything the player
+needs in one file instead:
+
+```bash
+great-docs termshow export docs/assets/my-demo.termshow --bundle
+```
+
+This writes `my-demo.termshow.json`, which you can copy, link to, and publish like any other file.
+An `-o` name ending in `.termshow.json` picks the bundle format without `--bundle`. Inside is the
+recording with its script applied, the same as a render: the screens, chapters, annotations,
+highlights, snippets and theme. It also has the recording's [transcript](#transcripts), which the
+player adds for screen readers.
+
+To play a bundle, point the [`<termshow-player>` element](#using-the-player-on-any-web-page)'s
+`src` at it, or the shortcode's `file` in [any Quarto project](#using-termshow-in-any-quarto-project):
+
+```{shortcodes="false"}
+{{< termshow file="my-demo.termshow.json" >}}
+```
+
+The file format is in [Bundles](termshow-file-formats.qmd#bundles).
+
 ## Exporting a GIF or Video
 
 Some places can't show an animated SVG either: pull request comments, chat messages, slides, and
@@ -1794,6 +1818,14 @@ warnings too, and pass several files to check them all at once:
 great-docs termshow validate docs/assets/*.termshow --strict
 ```
 
+The command also checks a [bundle](#exporting-a-bundle) or a render's `manifest.json`, for one
+written by another tool or edited by hand. Beyond the schema, it checks that the keyframes are in
+time order from 0, and that each refers to a screen, and each screen to rows, that the file has:
+
+```bash
+great-docs termshow validate my-demo.termshow.json
+```
+
 ## Best Practices
 
 These guidelines help produce recordings that are clear, fast-loading, and pleasant to watch:
@@ -2167,6 +2199,12 @@ This produces a `termshow/<name>/` directory containing SVG keyframes, a `manife
 [transcript](#transcripts) the shortcode puts after the player. Move or copy this directory into
 your Quarto project root if it isn't there already.
 
+Or export a [bundle](#exporting-a-bundle), one file you can keep anywhere in the project:
+
+```bash
+great-docs termshow export my-demo.termshow --bundle
+```
+
 ### Register termshow output as a resource
 
 Add the rendered output to your project's resources so Quarto includes it in the build output.
@@ -2178,6 +2216,8 @@ project:
     - termshow/**
 ```
 
+A bundle doesn't need this: the shortcode embeds all of it in the page.
+
 ### Embed with the shortcode
 
 Use the same `{{< termshow >}}` shortcode as in a Great Docs site:
@@ -2186,6 +2226,14 @@ Use the same `{{< termshow >}}` shortcode as in a Great Docs site:
 {{< termshow file="my-demo" autoplay="true" loop="true" >}}
 ```
 
+For a bundle, `file` is its path, relative to the document or else to the project root:
+
+```{shortcodes="false"}
+{{< termshow file="my-demo.termshow.json" autoplay="true" >}}
+```
+
+A bundle has no SVG files, so the page has no poster image before the player starts.
+
 All shortcode options (`autoplay`, `loop`, `speed`, `pause_on_chapters`, `controls`, `theme`) work
 identically. The extension handles CSS, JavaScript, and font injection automatically via Quarto's
 dependency system.
@@ -2255,17 +2303,21 @@ great-docs termshow assets site/player
 The command prints the tags that load them. The fonts must stay next to `termshow.css`, which
 loads them by relative URL.
 
-### Render the recording
+### Export the recording
 
-Render the recording into the site as well:
+Export the recording into the site as a [bundle](#exporting-a-bundle):
 
 ```bash
-great-docs termshow render my-demo.termshow -o site/termshow/my-demo
+great-docs termshow export my-demo.termshow -o site/my-demo.termshow.json
 ```
 
-The element doesn't show the [transcript](#transcripts) that the shortcode adds. To give screen
-readers the recording's text, put the transcript in the page next to the element, from
-`site/termshow/my-demo/_transcript.md` or `great-docs termshow transcript`.
+The bundle has the recording's [transcript](#transcripts), and the element puts it after the
+player, hidden from view but read by screen readers.
+
+A render directory works too (`great-docs termshow render my-demo.termshow -o
+site/termshow/my-demo`), but it has no transcript inside it. To give screen readers the recording's
+text, put the transcript in the page next to the element, from `site/termshow/my-demo/_transcript.md`
+or `great-docs termshow transcript`.
 
 ### Add the element
 
@@ -2276,33 +2328,34 @@ appear:
 <link rel="stylesheet" href="player/termshow.css">
 <script src="player/termshow.js"></script>
 
-<termshow-player src="termshow/my-demo" autoplay loop></termshow-player>
+<termshow-player src="my-demo.termshow.json" autoplay loop></termshow-player>
 ```
 
-`src` is the render directory, and the player loads the `manifest.json` inside it. It can also be
-the URL of a manifest file. Paths are relative to the page.
+`src` is the URL of a bundle or a manifest file, or a render directory, for which the player loads
+the `manifest.json` inside it. Paths are relative to the page.
 
-Most browsers won't load the manifest for a page opened straight from disk (a `file://` URL), so
-preview the page through a local server, such as `python -m http.server`. Or embed the manifest in
+Most browsers won't load the file for a page opened straight from disk (a `file://` URL), so
+preview the page through a local server, such as `python -m http.server`. Or embed the bundle in
 the element, which needs no server:
 
 ```html
 <termshow-player>
   <script type="application/json" class="gd-tp-manifest">
-    …the contents of manifest.json…
+    …the contents of my-demo.termshow.json…
   </script>
 </termshow-player>
 ```
 
-The build writes `manifest.json` so that it's safe to paste inside a `<script>` element.
+Bundles and `manifest.json` files are written so that they're safe to paste inside a `<script>`
+element.
 
 ### Element attributes
 
 The attributes match the [shortcode options](#options):
 
 | Attribute | Default | Description |
 |-----------|---------|-------------|
-| `src` | (none) | Render directory or manifest URL |
+| `src` | (none) | Bundle or manifest URL, or render directory |
 | `autoplay` | off | Start playing once loaded |
 | `loop` | off | Restart from the beginning at the end |
 | `speed` | `1` | Initial playback speed multiplier |
@@ -2345,8 +2398,8 @@ player.addEventListener("ready", () => player.seek(12));
 player.addEventListener("ended", () => console.log("done"));
 ```
 
-In a Quarto or Great Docs page, keep using the `termshow` shortcode: it embeds the manifest and a
-poster image in the page for you.
+In a Quarto or Great Docs page, keep using the `termshow` shortcode: it embeds the recording in the
+page for you.
 
 ## Next Steps
 

docs/user_guide/42-termshow-file-formats.qmd

@@ -20,7 +20,9 @@ everything you need.
 | `NAME.termshow.yml` | You, or the Termshow Editor | How to present it: settings, chapters, cuts, overlays |
 | `manifest.json` | `great-docs build` or `great-docs termshow render` | Everything the player needs, ready to embed in a page |
 
-The first two are source files you keep in your repository. The manifest is build output.
+The first two are source files you keep in your repository. The manifest is build output. A
+[bundle](#bundles) (`NAME.termshow.json`, from `great-docs termshow export --bundle`) is a manifest
+in a single file, with nothing else beside it.
 
 Each file has a JSON Schema (draft 2020-12). They ship with the `great-docs` package, under
 `great_docs/_term_player/schemas/`, and are published at these URLs:
@@ -29,7 +31,7 @@ Each file has a JSON Schema (draft 2020-12). They ship with the `great-docs` pac
 |------|--------|
 | `.termshow` | <https://raw.githubusercontent.com/posit-dev/great-docs/main/great_docs/_term_player/schemas/termshow-recording.schema.json> |
 | `.termshow.yml` | <https://raw.githubusercontent.com/posit-dev/great-docs/main/great_docs/_term_player/schemas/termshow-script.schema.json> |
-| `manifest.json` | <https://raw.githubusercontent.com/posit-dev/great-docs/main/great_docs/_term_player/schemas/termshow-manifest.schema.json> |
+| `manifest.json`, `.termshow.json` | <https://raw.githubusercontent.com/posit-dev/great-docs/main/great_docs/_term_player/schemas/termshow-manifest.schema.json> |
 
 ## Conventions
 
@@ -302,6 +304,7 @@ These members describe the whole recording:
 | `annotations` | no | Script annotations, with `at` renamed to `time` |
 | `highlights` | no | Script highlights, with `at` renamed to `time`; members at their default value are left out |
 | `snippets` | no | Script snippets, with `at` renamed to `time` |
+| `transcript` | no | The recording's text as Markdown; only in [bundles](#bundles) |
 
 ### Keyframes
 
@@ -315,7 +318,8 @@ is at time `0`. Several keyframes can share one screen, which is common during p
 - `frame` is an index into `frames`.
 - `file` names that screen's SVG file, relative to the manifest. It's written immediately after
   `time`, as shown. The SVG files serve as poster images, and as a fallback for players that
-  can't draw a frame themselves.
+  can't draw a frame themselves. A [bundle](#bundles) has no SVG files, so its keyframes have no
+  `file`: `{"time":4.5,"frame":12}`.
 
 ### Frames and lines
 
@@ -407,8 +411,8 @@ The build writes manifests as compact JSON with these properties, which consumer
 - No whitespace between tokens, and non-ASCII text written as-is, not as `\u` escapes.
 - `</` is written as `<\/`, so the JSON can be embedded in an HTML `<script>` element safely.
   (`<\/` is a valid JSON escape, so a JSON parser reads it back as `</`.)
-- `version` is the first member. In each keyframe, `file` immediately follows `time`. Tools
-  that can't parse JSON, such as the Quarto Lua filter, depend on these two orderings.
+- `version` is the first member. In each keyframe with a `file`, it immediately follows `time`.
+  Tools that can't parse JSON, such as the Quarto Lua filter, depend on these two orderings.
 
 ### Version 1 and versioning
 
@@ -418,14 +422,43 @@ Pages built by Great Docs 0.17 and earlier contain **version 1** manifests. Thes
 
 New optional members can be added without changing the version, since readers ignore members
 they don't recognize. A change that would break existing readers requires a new version number.
-Because every keyframe keeps its `file`, a player that meets a version it doesn't know can still
-show the SVG files.
+Because every keyframe in a render keeps its `file`, a player that meets a version it doesn't
+know can still show the SVG files. A bundle has no such fallback.
+
+## Bundles (`.termshow.json`) {#bundles}
+
+A bundle is a version 2 manifest that stands alone: everything the player needs is in one file,
+named `NAME.termshow.json`. `great-docs termshow export --bundle` writes one, and the
+[`<termshow-player>` element](terminal-recordings.qmd#using-the-player-on-any-web-page) and the
+shortcode both play it. It follows the manifest format above, with two differences:
+
+- keyframes have no `file` member, since there are no SVG files with it
+- it has a `transcript` member: the recording's text as Markdown, the same as `_transcript.md`
+  next to a render (see [Transcripts](terminal-recordings.qmd#transcripts))
+
+```json
+{"version":2,"title":"Install","duration":12.4,"term":{"cols":80,"rows":24},"keyframes":[{"time":0,"frame":0},…],"screen":{…},"lines":[…],"frames":[…],"transcript":"**Install**\n\n```console\n$ pip install my-tool\n```\n"}
+```
+
+It's serialized the same way as a manifest, so it's safe inside a `<script>` element too. The
+reference player puts the transcript after the player as a region named "Transcript of the
+terminal recording", hidden from view but read by screen readers. A player that doesn't use it
+should still offer the text some other way.
+
+The transcript's Markdown is limited to what `great-docs` writes, so a player can turn it into HTML
+without a full Markdown parser:
+
+- a chapter label is a paragraph in bold, `**Label**`
+- an annotation is a block quote, each line starting with `>`
+- the terminal's text is in a code block with the `console` language, fenced with three backticks,
+  or more when the text holds a run of three
+- outside code blocks, a backslash before any of `` \ ` * _ [ ] < > `` escapes it
 
 ## Validating files
 
 The quickest check is `great-docs termshow validate`, which applies these schemas without any extra
 packages and adds checks a schema can't express, such as annotations timed past the end of the
-recording (see [Validating a Recording](terminal-recordings.qmd#validating-a-recording)).
+recording, or a bundle's keyframes pointing at screens it doesn't have (see [Validating a Recording](terminal-recordings.qmd#validating-a-recording)).
 
 Any JSON Schema validator for draft 2020-12 can check these files too. The schemas validate one JSON
 value at a time, so a recording is checked line by line: the header against