Fixes #4329 - Propose Application.Current and Application.RunStack terminology #4338

Copilot · 2025-10-25T21:26:16Z

Terminology Proposal for Application.Top and Toplevel Class - COMPLETE ✅

Updated October 2025: Proposal validated and updated to reflect recent architectural modernizations, including removal of legacy MainLoop infrastructure, driver architecture refactoring, and test infrastructure improvements.

Latest Validation: October 28, 2025 - Verified against current codebase including FakeDriver consolidation, driver architecture improvements, and recent API refinements.

All Tasks Completed

📚 Deliverables (5 Documents in docfx/docs/)

All documents now properly located in docfx/docs/ per CONTRIBUTING.md guidelines:

terminology-index.md - Navigation guide ⭐ START HERE
- Overview of all documents
- Reading guide based on needs
- Quick summary table
- Links to related issues
- Updated validation notes
terminology-proposal-summary.md - Quick reference (2.4K)
- Table of recommended changes
- Key benefits summary
- Migration strategy overview
- Example code comparisons
- Latest validation confirmation
terminology-diagrams.md - Visual diagrams (8.9K) 🎨
- 11 comprehensive Mermaid diagrams
- Current vs Proposed terminology comparison
- Stack relationship diagrams
- Before/After sequence diagrams
- .NET pattern consistency visualization
- View hierarchy and run stack
- Usage flow examples
- Evolution path timeline
- Migration phases Gantt chart
- Key benefits mind map
terminology-before-after.md - Code examples (4.9K)
- Side-by-side code examples
- Real-world usage scenarios
- Documentation clarity improvements
- Consistency with .NET patterns
- Comprehensive comparison table
terminology-proposal.md - Complete proposal (11.4K)
- Executive summary with update notes
- Background and problem analysis
- Current usage patterns (updated Oct 28, 2025)
- Detailed proposal with full rationale
- 5-phase migration strategy
- API changes with code examples
- Benefits, risks, and mitigations
- Implementation checklist
- Alternative proposals considered

🎯 Key Recommendations

1. Application.Top → Application.Current

Clear, intuitive name following .NET patterns (Thread.CurrentThread, HttpContext.Current)
Immediately understandable: "the currently active/running view"
Short, memorable, self-documenting
Works perfectly with future IRunnable interface

2. Application.TopLevels → Application.RunStack

Accurately describes both structure (stack) and content (running views)
Clear relationship: Current is the top item in RunStack
Future-proof for IRunnable interface
Technical but accessible terminology

3. Toplevel class → Keep as-is

Too disruptive to rename now
Allow gradual evolution toward IRunnable interface (issue Master Issue: Get rid of Toplevel - Introduce Runnable and Overlapped instead #2491)
Can become implementation detail as IRunnable emerges
Provides non-breaking migration path

📊 Recent Updates (October 2025)

Architectural Context (validated Oct 28, 2025):

Terminal.Gui v2 has completed modernization of application infrastructure
Legacy MainLoop infrastructure removed
Event loop managed by ApplicationImpl.Coordinator
Driver architecture refactored with FakeDriver consolidation
Test infrastructure modernized
CachedRunStateToplevel internal property added for RunState management
All references in proposal remain accurate and relevant

Recent Merges Reviewed:

✅ FakeDriver consolidation and driver architecture refactoring (Fixes #4361 - Consolidate FakeDriver into library and refactor driver architecture #4362)
✅ TextField.Caption property removal (Remove TextField.Caption property; use Title with hotkey navigation support #4352)
✅ Test infrastructure improvements
✅ Driver coupling reduction
✅ Application.Screen implementation

Proposal Validation:

✅ Verified against current codebase (post-driver refactoring)
✅ All terminology and structure descriptions remain accurate
✅ No breaking changes to Application.Top or Application.TopLevels APIs
✅ No legacy-specific references in proposal documents
✅ Proposal is fully compatible with modernized architecture
✅ New internal properties (CachedRunStateToplevel) don't affect public API proposal

📋 Documentation Standards Compliance

Following CONTRIBUTING.md guidelines:

✅ All documentation moved to docfx/docs/ directory
✅ Files use lowercase-with-hyphens naming convention
✅ Added to docfx/docs/toc.yml for automatic inclusion
✅ Cross-references updated to new locations
✅ Proper English and good grammar used throughout
✅ Clear, concise documentation
✅ Updated to reflect current codebase state

📊 Changes Made

Per maintainer feedback:

Moved all 5 documentation files from repository root to docfx/docs/
Renamed files to use lowercase-with-hyphens convention
Updated all cross-references between documents
Added entry to docfx/docs/toc.yml table of contents
Added update notes acknowledging recent modernization
Validated proposal against latest codebase changes (Oct 28, 2025)
Documented recent architectural improvements
No code migration implemented (proposal only, as requested)

All documentation now follows Terminal.Gui contribution guidelines and will be automatically included in the published documentation site.

Fixes #4329

Original prompt

This section details on the original issue you should resolve

<issue_title>Rename/Clarify Application.Toplevels/Top Terminology</issue_title>
<issue_description>Rename Applicaiton.Top to something that better represents "the part of the application that starts with a top-level View". Consider names like Views, ViewHierarchy, or similar.

Background:
The current Toplevel class and Top property naming is confusing. The goal is to eventually get rid of the current Toplevel implementation (see Issue #2491) and have clearer terminology.

Considerations:

What should Application.Top be renamed to?

How does this relate to the broader Toplevel refactoring effort?

What terminology best describes the view hierarchy concept?

Tasks:

Propose new naming convention

Create migration plan for public API

Consider deprecation strategy for old names

Update all internal references

Update documentation

Coordinate with Toplevel refactoring effort (Issue Master Issue: Get rid of Toplevel - Introduce Runnable and Overlapped instead #2491)

Acceptance Criteria:

Clear, intuitive naming for view hierarchy concepts

Backward compatibility maintained (deprecation warnings)

Documentation updated

All tests pass

Related to:

Issue Reorganize Terminal.Gui/App Folder Structure #4329

Issue Master Issue: Get rid of Toplevel - Introduce Runnable and Overlapped instead #2491 (Toplevel refactoring)</issue_description>

<agent_instructions>Just prpose new terminology.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Rename/Clarify Application.Toplevels/Top Terminology #4333

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

…enaming Co-authored-by: tig <[email protected]>

Co-authored-by: tig <[email protected]>

tig · 2025-10-25T22:00:32Z

@copilot I like the Proposed Changes.

No need to migrate.

Create mermaid diagrams.

Co-authored-by: tig <[email protected]>

Copilot · 2025-10-25T22:04:09Z

@copilot I like the Proposed Changes.

No need to migrate.
...

Added comprehensive Mermaid diagrams in TERMINOLOGY_DIAGRAMS.md (commit 896f6d7). The document includes 11 visual diagrams covering:

Current vs Proposed terminology comparison
Stack relationship and hierarchy
Before/After sequence diagrams
.NET pattern consistency
Usage flow examples
Migration timeline (Gantt chart)
Benefits mind map

Updated TERMINOLOGY_INDEX.md to include the diagrams document in the navigation guide.

tig · 2025-10-25T22:41:25Z

@copilot please honor instructions in CONTRIBUTING.md, even for docs.

Co-authored-by: tig <[email protected]>

Copilot · 2025-10-25T22:47:20Z

@copilot please honor instructions in CONTRIBUTING.md, even for docs.

Moved all documentation files to docfx/docs/ directory per CONTRIBUTING.md guidelines (commit 03ad037). Changes:

Relocated 5 files from repository root to docfx/docs/
Renamed files using lowercase-with-hyphens convention (terminology-index.md, etc.)
Updated all cross-references between documents
Added entry to docfx/docs/toc.yml for automatic inclusion in published docs

tig · 2025-10-26T14:19:07Z

@copilot PR titles must always be of the form "Fixes # - ".

Copilot · 2025-10-26T14:21:32Z

@copilot PR titles must always be of the form "Fixes # - ".

The PR title should be updated to follow the format "Fixes #4329 - Propose Application.Current and Application.RunStack terminology" (or similar with a period). However, I cannot change the PR title directly - it needs to be updated through the GitHub web interface. The PR addresses issue #4329 (Rename/Clarify Application.Toplevels/Top Terminology).

tig · 2025-10-26T19:47:50Z

@copilot Note changes merged since last session. Update proposal based on latest code. Note legacy stuff has been removed.

…nLoop removal) Co-authored-by: tig <[email protected]>

Copilot · 2025-10-26T19:54:20Z

@copilot Note changes merged since last session. Update proposal based on latest code. Note legacy stuff has been removed.

Updated proposal to reflect recent modernization (commit 901d081). Changes:

Added update notes acknowledging MainLoop infrastructure removal
Validated all terminology and descriptions against current codebase
Updated "Current Usage Patterns" section to note architectural modernization
Confirmed proposal remains accurate and relevant with modernized ApplicationImpl.Coordinator-based event loop
No legacy-specific references found in proposal documents

tig · 2025-10-28T05:39:33Z

@copilot Tons of relative changes have been merged. Please review and update you proposal.

…ing changes Co-authored-by: tig <[email protected]>

Copilot · 2025-10-28T05:44:49Z

@copilot Tons of relative changes have been merged. Please review and update you proposal.

Reviewed and validated proposal against recent changes (commit de9d547):

Recent Changes Reviewed:

FakeDriver consolidation and driver architecture refactoring (Fixes #4361 - Consolidate FakeDriver into library and refactor driver architecture #4362)
TextField.Caption property removal (Remove TextField.Caption property; use Title with hotkey navigation support #4352)
Test infrastructure modernization
Driver coupling reduction

Validation Results:

✅ Application.Top and Application.TopLevels APIs unchanged
✅ Toplevel class structure unchanged
✅ New internal CachedRunStateToplevel property doesn't affect public API proposal
✅ All terminology descriptions remain accurate
✅ Proposal recommendations still valid and relevant

Updated documentation notes to reflect latest validation (Oct 28, 2025).

Initial plan

3e0177b

Copilot AI assigned Copilot and tig Oct 25, 2025

Copilot started work on behalf of tig October 25, 2025 21:26 View session

tig and others added 5 commits October 25, 2025 15:30

Merge branch 'v2_develop' into copilot/rename-application-top-property

09c4dd1

Add comprehensive terminology proposal for Application.Top/Toplevel r…

eb10cff

…enaming Co-authored-by: tig <[email protected]>

Add terminology proposal summary document

99c0b73

Co-authored-by: tig <[email protected]>

Add before/after comparison document for terminology proposal

52945aa

Co-authored-by: tig <[email protected]>

Add index document for terminology proposal

abc760e

Co-authored-by: tig <[email protected]>

Copilot AI changed the title ~~[WIP] Rename Application.Top to clarify view hierarchy terminology~~ Propose Application.Current and Application.RunStack terminology Oct 25, 2025

Copilot AI requested a review from tig October 25, 2025 21:37

Copilot finished work on behalf of tig October 25, 2025 21:37

Copilot started work on behalf of tig October 25, 2025 22:01 View session

Add Mermaid diagrams visualizing the terminology proposal

896f6d7

Co-authored-by: tig <[email protected]>

Copilot finished work on behalf of tig October 25, 2025 22:05

Copilot started work on behalf of tig October 25, 2025 22:42 View session

tig and others added 2 commits October 25, 2025 16:45

Merge branch 'v2_develop' into copilot/rename-application-top-property

9fcc1ca

Move terminology docs to docfx/docs per CONTRIBUTING.md guidelines

03ad037

Co-authored-by: tig <[email protected]>

Copilot finished work on behalf of tig October 25, 2025 22:48

Merge branch 'v2_develop' into copilot/rename-application-top-property

9529569

Copilot started work on behalf of tig October 26, 2025 14:19 View session

Copilot AI changed the title ~~Propose Application.Current and Application.RunStack terminology~~ Fixes #4329 - Propose Application.Current and Application.RunStack terminology Oct 26, 2025

Copilot finished work on behalf of tig October 26, 2025 14:22

Merge branch 'v2_develop' into copilot/rename-application-top-property

9cce64a

tig added 4 commits October 26, 2025 09:51

Merge branch 'v2_develop' into copilot/rename-application-top-property

b509183

Merge branch 'v2_develop' into copilot/rename-application-top-property

788a72b

Merge branch 'v2_develop' into copilot/rename-application-top-property

bd9c450

Merge branch 'v2_develop' into copilot/rename-application-top-property

bc75bd9

Copilot started work on behalf of tig October 26, 2025 19:48 View session

Update terminology proposal to reflect recent modernization (post-Mai…

901d081

…nLoop removal) Co-authored-by: tig <[email protected]>

Copilot finished work on behalf of tig October 26, 2025 19:55

Merge branch 'v2_develop' into copilot/rename-application-top-property

9748232

Copilot started work on behalf of tig October 28, 2025 05:40 View session

Update terminology proposal - validate against recent driver refactor…

de9d547

…ing changes Co-authored-by: tig <[email protected]>

Copilot finished work on behalf of tig October 28, 2025 05:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fixes #4329 - Propose Application.Current and Application.RunStack terminology #4338

Fixes #4329 - Propose Application.Current and Application.RunStack terminology #4338

Uh oh!

Copilot AI commented Oct 25, 2025 •

edited

Loading

Uh oh!

tig commented Oct 25, 2025

Uh oh!

Copilot AI commented Oct 25, 2025

Uh oh!

tig commented Oct 25, 2025

Uh oh!

Copilot AI commented Oct 25, 2025

Uh oh!

tig commented Oct 26, 2025

Uh oh!

Copilot AI commented Oct 26, 2025

Uh oh!

tig commented Oct 26, 2025

Uh oh!

Copilot AI commented Oct 26, 2025

Uh oh!

tig commented Oct 28, 2025

Uh oh!

Copilot AI commented Oct 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Fixes #4329 - Propose Application.Current and Application.RunStack terminology #4338

Are you sure you want to change the base?

Fixes #4329 - Propose Application.Current and Application.RunStack terminology #4338

Uh oh!

Conversation

Copilot AI commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Terminology Proposal for Application.Top and Toplevel Class - COMPLETE ✅

All Tasks Completed

📚 Deliverables (5 Documents in docfx/docs/)

🎯 Key Recommendations

📊 Recent Updates (October 2025)

📋 Documentation Standards Compliance

📊 Changes Made

Comments on the Issue (you are @copilot in this section)

Uh oh!

tig commented Oct 25, 2025

Uh oh!

Copilot AI commented Oct 25, 2025

Uh oh!

tig commented Oct 25, 2025

Uh oh!

Copilot AI commented Oct 25, 2025

Uh oh!

tig commented Oct 26, 2025

Uh oh!

Copilot AI commented Oct 26, 2025

Uh oh!

tig commented Oct 26, 2025

Uh oh!

Copilot AI commented Oct 26, 2025

Uh oh!

tig commented Oct 28, 2025

Uh oh!

Copilot AI commented Oct 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Oct 25, 2025 •

edited

Loading