Add tuirec recording guide and hero-gif docs by tig · Pull Request #5396 · gui-cs/Terminal.Gui

tig · 2026-05-24T13:18:52Z

Summary

Adds IDesignable.GetDemoKeyStrokes() to the framework and implements automated GIF recording infrastructure for Terminal.Gui views documentation.

API Changes

IDesignable.GetDemoKeyStrokes() — new default interface method returning a tuirec-format keystroke string (or null for static views). Implemented on 15 views: Button, TextField, TextView, ListView, OptionSelector, FlagSelector, DropDownList, Tabs, SpinnerView, TreeView, TableView, DateEditor, TimeEditor, HexView, ColorPicker.

Tooling Changes

OutputView (docfx/scripts/OutputView/): Added --live mode (runs without StopAfterFirstIteration for tuirec recording) and --keystrokes mode (queries GetDemoKeyStrokes() for a view type). Fixed generic type resolution.
generate-views-doc.ps1: Rewritten to use tuirec for GIF recording instead of ANSI-to-HTML conversion. Uses cross-platform dotnet <dll> invocation.

Documentation

Added Scripts/tuirec/README.md — comprehensive recording guide
Added Scripts/tuirec/hero-gif.md — quick reference
All .exe references replaced with cross-platform dotnet <dll> invocation
Fixed quit key references: Ctrl+Q → Escape throughout

GIFs

39 view GIFs in docfx/images/views/ (373KB total)
1 CharacterMap scenario GIF in Examples/UICatalog/Scenarios/CharacterMap/

Upstream Issues Filed

gui-cs/tuirec#64 — preroll/postroll blank frames in recordings

Add hero-gif.md as a minimal pointer to the recording guide. Add Scripts/tuirec.md with the full recording workflow, validation checklist, agent guidance, and TBD sections for UICatalog scenarios, EnableForDesign views, and standalone example apps. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Rewrote Scripts/tuirec.md with comprehensive agent-oriented guidance for recording UICatalog scenarios using gui-cs/tuirec - Includes install steps, keystroke composition, PowerShell quoting, --kitty-keyboard decision tree, troubleshooting, and validation checklist - Added working CharMap scenario recording (docfx/images/charmap.gif) - Updated hero-gif.md with quick-reference recording command Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Corrected the framing: this is a tuirec encoding bug (sends fabricated CSI u codepoints for nav keys), not a Terminal.Gui parsing issue. Filed gui-cs/tuirec#54 with full spec analysis. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig · 2026-05-24T13:48:23Z

Superseded by PR #5393 which consolidates all Spectre interop work.

Re-recorded with a focused demo script that: - Scrolls briefly to show charmap responsiveness - Uses CollectionNavigator typing to jump to Box Drawing category - Jumps to Emojis Symbols category to show emoji rendering - Opens context menu (Shift+F10) on a glyph - Updates tuirec.md example to document these techniques Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig · 2026-05-24T13:56:25Z

Feedback from using tuirec guidance to record SpectreView scenario

The recording succeeded first try using ScenarioRunner + tuirec record. Here are suggestions for the TBD sections:

For "Recording UICatalog Scenarios" section:

Document that ScenarioRunner run <Name> is the correct binary/args pattern
Note: build ScenarioRunner first (dotnet build Examples/ScenarioRunner)
Recommend --startup-delay 1500 for TG apps (they need time to render initial frame)

Show the standard pattern:

tuirec record \
  --binary Examples/ScenarioRunner/bin/Debug/net10.0/ScenarioRunner \
  --args run,<ScenarioName> \
  --name <scenario-kebab> \
  --show-command "dotnet run -- run <Name>" \
  --cols 100 --rows 30 \
  --startup-delay 1500 \
  --keystrokes "wait:1500,<script>,Ctrl+Q"

OptionSelector navigation uses CursorDown/CursorUp key names
Add --drain 500 to capture the final frame before exit
Output GIF should go to Examples/UICatalog/Scenarios/<ScenarioName>.gif

For "Recording Individual View Sub-classes with EnableForDesign":

Needs a dedicated lightweight runner that instantiates a single View with EnableForDesign
Not yet clear how this would be scripted - may need a new mini-app

For "Recording Standalone Example Apps":

Similar to ScenarioRunner but --binary points directly at the example exe
Example: --binary Examples/Example/bin/Debug/net10.0/Example

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Re-record using Box Drawing + Arrows instead of Emojis (wide glyphs cause misaligned rendering in agg output) - Add 'Avoid wide glyphs' principle to recording guidance - Add 'Output File Placement' section: GIFs go alongside scenario code at Examples/UICatalog/Scenarios/<Dir>/<Name>.gif - Add wide-glyph troubleshooting entry - Use PascalCase --name matching the scenario class name Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Move Scripts/tuirec.md -> Scripts/tuirec/README.md - Move hero-gif.md -> Scripts/tuirec/hero-gif.md - Update file placement guidance: GIFs and optional *-tuirec.ps1 scripts live alongside the .cs file they document - Fix quit key: Escape is the default (not Ctrl+Q) - Add guidance for View-derived class GIF placement Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Agents should follow the general workflow in README.md rather than creating per-scenario tuirec scripts. If something is unclear enough that an agent creates a bespoke script, the README should be improved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

New sequence: Tab to category list, A (Arrows), Bo (Box Drawing), E (Emoji), Tab back to grid, context menu, quit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Sequence: Tab to categories, Arrows -> Box Drawing -> Emoji, Tab back to grid, context menu, quit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add GetDemoKeyStrokes() to IDesignable interface returning tuirec-format keystroke strings for recording demo GIFs of each view - Implement for: Button, TextField, ListView, OptionSelector, DropDownList, Tabs, SpinnerView, ProgressBar - Add --live and --keystrokes flags to OutputView: --live: keeps app running for tuirec recording --keystrokes: queries view's demo keystrokes and prints to stdout - Rewrite generate-views-doc.ps1 to use tuirec instead of ANSI->HTML rendering. GIFs go to docfx/images/views/ and views.md embeds them as markdown images. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Added GetDemoKeyStrokes() to: FlagSelector, TextView, TreeView, TableView, DateEditor, TimeEditor, HexView, ColorPicker - Fixed OptionSelector: added Space to activate selected item - Fixed DropDownList: use F4 to open, made override of TextField's virtual method - Fixed TextView: use backtick-wrapped literal text for tuirec - Generated 39 view GIFs in docfx/images/views/ with trimmed pre/postroll Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0ee7561f88

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Adds a tuirec-based workflow for capturing consistent Terminal.Gui demo recordings (GIFs/casts), and wires up view-level “demo keystroke” metadata so tooling can automatically drive interactive captures (not just static renders).

Changes:

Add IDesignable.GetDemoKeyStrokes() (tuirec token string) and implement it across multiple built-in views.
Extend the DocFX OutputView tool with --live (interactive run) and --keystrokes (query demo script) modes.
Add Scripts/tuirec documentation and update the DocFX view-doc generator to record per-view GIFs using tuirec.

Reviewed changes

Copilot reviewed 21 out of 61 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
Terminal.Gui/ViewBase/IDesignable.cs	Adds `GetDemoKeyStrokes()` default interface method + docs.
Terminal.Gui/Views/Button.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/Color/ColorPicker.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/DropDownList.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/HexView.cs	Adds demo keystrokes (explicit interface impl).
Terminal.Gui/Views/ListView/ListView.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/ProgressBar.cs	Adds `GetDemoKeyStrokes()` override (currently returns null).
Terminal.Gui/Views/Selectors/FlagSelector.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/Selectors/OptionSelector.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/SpinnerView/SpinnerView.cs	Adds demo keystrokes (explicit interface impl) for animation recording.
Terminal.Gui/Views/TableView/TableView.cs	Adds demo keystrokes (explicit interface impl).
Terminal.Gui/Views/Tabs.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/TextInput/DateEditor.cs	Adds demo keystrokes (explicit interface impl).
Terminal.Gui/Views/TextInput/TextField/TextField.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/TextInput/TextView/TextView.cs	Provides demo keystroke script for recording.
Terminal.Gui/Views/TextInput/TimeEditor.cs	Adds demo keystrokes (explicit interface impl).
Terminal.Gui/Views/TreeView/TreeView.cs	Provides demo keystroke script for recording.
Scripts/tuirec/README.md	Comprehensive tuirec recording guide.
Scripts/tuirec/hero-gif.md	Short “hero GIF” pointer/quick reference to the guide.
docfx/scripts/OutputView/OutputView.cs	Adds `--live` run mode + `--keystrokes` query mode for tooling.
docfx/scripts/generate-views-doc.ps1	Switches from static render capture to tuirec-driven GIF generation per view.

…solution, cross-platform paths - Remove redundant ProgressBar.GetDemoKeyStrokes() (default returns null) - Add app.Dispose() on early return in OutputView non-live path - Fix generic view type resolution (e.g. ListView`1) via assembly scan - Replace hard-coded .exe paths with cross-platform dotnet <dll> invocation - Remove unused $repoRoot variable in generate-views-doc.ps1 - Use built binary instead of dotnet run for keystroke queries - Fix --startup-delay from 1500 to 0 in generate-views-doc.ps1 - Add GetDemoKeyStrokesTests covering all IDesignable implementations Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Note this is a new API added in v2 - Clarify that both null and empty string mean no interactive demo Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Upgrade to tuirec v0.4.2 which has built-in --trim for preroll/postroll - Fix Code.gif: skip white-on-black scheme override in live mode so syntax highlighting colors are preserved - Add wait:500 before final Escape so last meaningful frame has dwell time - Prevent child Accept from bubbling up in live mode (CommandsToBubbleUp = []) - Script retries with --trim=false when validation fails (1-frame GIFs) - Re-record all 39 view GIFs with improved pipeline Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…r all views OutputView now writes a concealed ANSI character before TG renders, creating a 500ms time gap that guarantees 2+ visually distinct frames for --trim. This eliminates the dark first-frame preroll artifact for ALL views without needing the --trim=false fallback. Added GetDemoKeyStrokes() to 12 views: Bar, CharMap, Code, GraphView, Label, Link, MenuBar, ProgressBar, ScrollBar, Shortcut, StatusBar, Wizard. All 39 GIFs now record with --trim successfully (zero fallbacks). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The concealed attribute (\x1b[8m) isn't honored by agg, causing a visible white dot in the first GIF frame. Fix by setting the dot's foreground color to match the monokai theme background (#272822 = RGB 39,40,34), making it truly invisible. Also switch static-view fallback from Tab to click:40:10 which more reliably triggers visual changes (fixes PopoverMenu). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The 500ms Thread.Sleep created a visible ~1s blank gray screen at the start of each GIF. Reduced to 50ms which is enough for --trim frame detection but imperceptible in the final GIF. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…FileDialog - CharMap: page down 40x then context menu (Shift+F10) - Tabs: navigate to Settings tab, press Alt+I 4x, select RoundedDotted style - TreeView: expand nodes with Space - Markdown: scroll down 50x to show content - FileDialog: navigate type filter, filter by .md, select file - Add --mouse-pointer none to all recordings - Add GetDemoKeyStrokes() to Markdown and FileDialog Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove .cast files, local_packages, and artifacts/ directories. Remove --cast-output from generate script (not needed in repo). Add --mouse-pointer none to fallback retry. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add <img> tags referencing view GIFs in the <remarks> section of 38 view class XML docs. These will display animated demos in the published API documentation. Also: - Remove PopoverMenu GIF (can't render in isolation as a popover) - Add GetDemoKeyStrokes() to Markdown and FileDialog - Fix test to use ImageView for null-returning default interface check - Add Markdown and ProgressBar to non-null keystroke test cases Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

BDisp

Impressive work. The idea of automating preview recordings is very good.

tig and others added 3 commits May 24, 2026 07:18

tig added a commit that referenced this pull request May 24, 2026

Remove hero-gif.md, tuirec.md, and GIF (moved to PR #5396)

ed798ae

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig closed this May 24, 2026

tig and others added 2 commits May 24, 2026 07:57

Move charmap.gif to scenario directory

2269ba1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig reopened this May 24, 2026

tig and others added 3 commits May 24, 2026 12:57

Update CharMap keystroke script: Arrows -> Box Drawing -> Emoji

17eaef5

New sequence: Tab to category list, A (Arrows), Bo (Box Drawing), E (Emoji), Tab back to grid, context menu, quit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig force-pushed the tig/fix-hero-gif-tuirec-docs branch from 8a10345 to 4b736a5 Compare May 24, 2026 19:22

Re-record CharacterMap.gif with updated keystroke script

156dfbe

Sequence: Tab to categories, Arrows -> Box Drawing -> Emoji, Tab back to grid, context menu, quit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig force-pushed the tig/fix-hero-gif-tuirec-docs branch from 4b736a5 to 156dfbe Compare May 24, 2026 19:24

tig marked this pull request as draft May 24, 2026 21:12

Fix View GIF placement: docfx/images/views/, not alongside .cs

53b53ec

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig force-pushed the tig/fix-hero-gif-tuirec-docs branch from 93e763f to 53b53ec Compare May 24, 2026 21:15

tig marked this pull request as ready for review May 24, 2026 22:49

tig requested a review from Copilot May 24, 2026 22:49

Copilot started reviewing on behalf of tig May 24, 2026 22:49 View session

chatgpt-codex-connector Bot reviewed May 24, 2026

View reviewed changes

Comment thread docfx/scripts/generate-views-doc.ps1 Outdated

Copilot AI reviewed May 24, 2026

View reviewed changes

tig and others added 3 commits May 24, 2026 17:17

Update IDesignable.GetDemoKeyStrokes XML docs per review feedback

81eaa6d

- Note this is a new API added in v2 - Clarify that both null and empty string mean no interactive demo Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig and others added 8 commits May 25, 2026 13:58

feat: update CharMap demo to page down 30x then show context menu

051d1af

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chore: remove stray images/views/PopoverMenu.gif

3d6d0c3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tig requested a review from BDisp May 25, 2026 22:34

BDisp approved these changes May 25, 2026

View reviewed changes

tig merged commit 2a73083 into develop May 25, 2026
13 checks passed

tig deleted the tig/fix-hero-gif-tuirec-docs branch May 25, 2026 23:29

dependabot Bot mentioned this pull request Jun 5, 2026

Bump the non-major-updates group with 1 update Akeoott/ZenMonitor#27

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add tuirec recording guide and hero-gif docs#5396

Add tuirec recording guide and hero-gif docs#5396
tig merged 24 commits into
developfrom
tig/fix-hero-gif-tuirec-docs

tig commented May 24, 2026 •

edited

Loading

Uh oh!

tig commented May 24, 2026

Uh oh!

tig commented May 24, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BDisp left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tig commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

API Changes

Tooling Changes

Documentation

GIFs

Upstream Issues Filed

Uh oh!

tig commented May 24, 2026

Uh oh!

tig commented May 24, 2026

Feedback from using tuirec guidance to record SpectreView scenario

For "Recording UICatalog Scenarios" section:

For "Recording Individual View Sub-classes with EnableForDesign":

For "Recording Standalone Example Apps":

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BDisp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tig commented May 24, 2026 •

edited

Loading