Skip to content

Add tuirec recording guide and hero-gif docs#5396

Open
tig wants to merge 10 commits into
developfrom
tig/fix-hero-gif-tuirec-docs
Open

Add tuirec recording guide and hero-gif docs#5396
tig wants to merge 10 commits into
developfrom
tig/fix-hero-gif-tuirec-docs

Conversation

@tig
Copy link
Copy Markdown
Member

@tig tig commented May 24, 2026

Process documentation for capturing GIFs/recordings of Terminal.Gui apps and scenarios.

Changes

  • hero-gif.md — minimal root-level pointer to the recording guide
  • Scripts/tuirec.md — comprehensive recording guide covering:
    • Recommended workflow (build → launch → record → export → validate)
    • Practical guidance for AI agents
    • Validation checklist
    • TBD sections for UICatalog scenarios, EnableForDesign views, and standalone example apps

These docs support the hero-GIF workflow discussed in #5393.

tig and others added 3 commits May 24, 2026 07:18
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>
tig added a commit that referenced this pull request May 24, 2026
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@tig
Copy link
Copy Markdown
Member Author

tig commented May 24, 2026

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

@tig tig closed this May 24, 2026
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
Copy link
Copy Markdown
Member Author

tig commented May 24, 2026

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

tig and others added 2 commits May 24, 2026 07:57
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>
@tig tig reopened this May 24, 2026
tig and others added 4 commits May 24, 2026 12:57
- 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant