Update proposal: RunStack → SessionStack to align with SessionToken terminology

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

docfx/docs/terminology-before-after.md

@@ -29,8 +29,8 @@ var focused = Application.Top.MostFocused;
 // Immediately clear: the currently active view
 Application.Current?.SetNeedsDraw();
 
-// Clear relationship: Current is from the RunStack
-if (Application.RunStack.Count > 0)
+// Clear relationship: Current is from the SessionStack
+if (Application.SessionStack.Count > 0)
 {
     var current = Application.Current;
 }
@@ -41,8 +41,8 @@ var focused = Application.Current.MostFocused;
 
 **Benefits:**
 - `Current` is immediately understandable
-- `RunStack` describes both structure (stack) and content (running views)
-- Clear relationship: `Current` is the top item in `RunStack`
+- `SessionStack` describes both structure (stack) and content (running views)
+- Clear relationship: `Current` is the top item in `SessionStack`
 
 ## Real-World Code Examples
 
@@ -86,10 +86,10 @@ public bool HasModalDialog()
 
 **After:**
 ```csharp
-// Clear: multiple items in the RunStack means we have modals/overlays
+// Clear: multiple items in the SessionStack means we have modals/overlays
 public bool HasModalDialog()
 {
-    return Application.RunStack.Count > 1 
+    return Application.SessionStack.Count > 1 
         && Application.Current?.Modal == true;
 }
 ```
@@ -132,7 +132,7 @@ public static Toplevel? Top { get; }
 ```csharp
 /// <summary>
 /// Gets the currently active view with its own run loop.
-/// This is the view at the top of the <see cref="RunStack"/>.
+/// This is the view at the top of the <see cref="SessionStack"/>.
 /// </summary>
 /// <remarks>
 /// The current view receives all keyboard and mouse input and is 
@@ -180,7 +180,7 @@ If Terminal.Gui used the .NET pattern:
 
 ## Conclusion
 
-The proposed terminology (`Application.Current` and `Application.RunStack`) provides:
+The proposed terminology (`Application.Current` and `Application.SessionStack`) provides:
 - **Immediate clarity** without needing to read documentation
 - **Consistency** with established .NET patterns
 - **Better code readability** through self-documenting names

docfx/docs/terminology-diagrams.md

@@ -20,7 +20,7 @@ graph TB
     
     subgraph Proposed["Proposed Terminology (Clear)"]
         B1[Application.Current]
-        B2[Application.RunStack]
+        B2[Application.SessionStack]
         B3[Toplevel class<br/>keep as-is]
         
         B1 -->|"top item in"| B2
@@ -38,7 +38,7 @@ graph TB
 
 ```mermaid
 graph TD
-    subgraph RunStack["Application.RunStack (ConcurrentStack&lt;Toplevel&gt;)"]
+    subgraph SessionStack["Application.SessionStack (ConcurrentStack&lt;Toplevel&gt;)"]
         direction TB
         Dialog[Dialog<br/>Modal: true]
         Window[Window<br/>Modal: false]
@@ -89,10 +89,10 @@ sequenceDiagram
     Dev->>Code: Application.Current?
     Code->>Dev: ✓ Obviously the current view!
     
-    Dev->>Code: Application.RunStack?
+    Dev->>Code: Application.SessionStack?
     Code->>Dev: ✓ Stack of running views!
     
-    Dev->>Code: Current from RunStack?
+    Dev->>Code: Current from SessionStack?
     Code->>Dev: ✓ Top item in the stack!
     
     Note over Dev,API: Self-documenting, no docs needed
@@ -140,7 +140,7 @@ graph TB
         Content --> Button2
     end
     
-    subgraph Stack["Application.RunStack"]
+    subgraph Stack["Application.SessionStack"]
         direction TB
         S1[Window<br/>Currently Active]
         S2[Previous Toplevel<br/>Waiting]
@@ -163,23 +163,23 @@ sequenceDiagram
     participant Main as Main Window
     participant Dialog as Dialog
     
-    Note over App: Initially empty RunStack
+    Note over App: Initially empty SessionStack
     
     App->>Main: Run(mainWindow)
     activate Main
-    Note over App: RunStack: [Main]<br/>Current: Main
+    Note over App: SessionStack: [Main]<br/>Current: Main
     
     Main->>Dialog: Run(dialog)
     activate Dialog
-    Note over App: RunStack: [Dialog, Main]<br/>Current: Dialog
+    Note over App: SessionStack: [Dialog, Main]<br/>Current: Dialog
     
     Dialog->>App: RequestStop()
     deactivate Dialog
-    Note over App: RunStack: [Main]<br/>Current: Main
+    Note over App: SessionStack: [Main]<br/>Current: Main
     
     Main->>App: RequestStop()
     deactivate Main
-    Note over App: RunStack: []<br/>Current: null
+    Note over App: SessionStack: []<br/>Current: null
 ```
 
 ## Terminology Evolution Path
@@ -194,7 +194,7 @@ graph LR
     
     subgraph Phase1["Phase 1: Add New APIs"]
         P1[Application.Current]
-        P2[Application.RunStack]
+        P2[Application.SessionStack]
         P3[Toplevel class]
         P1O["Application.Top<br/>[Obsolete]"]
         P2O["Application.TopLevels<br/>[Obsolete]"]
@@ -202,7 +202,7 @@ graph LR
     
     subgraph Phase2["Phase 2-4: Migration"]
         M1[Application.Current]
-        M2[Application.RunStack]
+        M2[Application.SessionStack]
         M3[Toplevel class]
         M1O["Application.Top<br/>[Obsolete Warning]"]
         M2O["Application.TopLevels<br/>[Obsolete Warning]"]
@@ -210,7 +210,7 @@ graph LR
     
     subgraph Future["Phase 5: Future State"]
         F1[Application.Current]
-        F2[Application.RunStack]
+        F2[Application.SessionStack]
         F3["IRunnable interface"]
         F4["Toplevel : IRunnable"]
     end
@@ -282,7 +282,7 @@ gantt
 
 ```mermaid
 mindmap
-  root((Application.Current<br/>& RunStack))
+  root((Application.Current<br/>& SessionStack))
     Clarity
       Self-documenting
       No ambiguity
@@ -309,13 +309,13 @@ mindmap
 
 These diagrams illustrate:
 
-1. **Clear Relationships**: The new terminology makes the relationship between `Current` and `RunStack` obvious
+1. **Clear Relationships**: The new terminology makes the relationship between `Current` and `SessionStack` obvious
 2. **Self-Documenting**: Names that immediately convey their purpose without documentation
 3. **.NET Alignment**: Consistency with established .NET framework patterns
 4. **Migration Safety**: Backward-compatible approach with clear phases
 5. **Future-Proof**: Supports evolution toward `IRunnable` interface
 
-The proposed terminology (`Application.Current` and `Application.RunStack`) provides immediate clarity while maintaining compatibility and supporting future architectural improvements.
+The proposed terminology (`Application.Current` and `Application.SessionStack`) provides immediate clarity while maintaining compatibility and supporting future architectural improvements.
 
 ---
 

docfx/docs/terminology-index.md

@@ -60,7 +60,7 @@ Complete, comprehensive proposal with all analysis, rationale, and implementatio
 | Current | Proposed | Why |
 |---------|----------|-----|
 | `Application.Top` | `Application.Current` | Clear, follows .NET patterns, self-documenting |
-| `Application.TopLevels` | `Application.RunStack` | Describes structure and content accurately |
+| `Application.TopLevels` | `Application.SessionStack` | Describes structure and content accurately |
 | `Toplevel` class | Keep (for now) | Allow evolution to `IRunnable` interface |
 
 ### Key Benefits

docfx/docs/terminology-proposal-summary.md

@@ -11,7 +11,7 @@ This is a brief summary of the [full terminology proposal](terminology-proposal.
 | Current Name | Proposed Name | Rationale |
 |--------------|---------------|-----------|
 | `Application.Top` | `Application.Current` | Clear, follows .NET patterns (e.g., `Thread.CurrentThread`), indicates "currently active" |
-| `Application.TopLevels` | `Application.RunStack` | Descriptive of the stack structure, pairs well with `Current` |
+| `Application.TopLevels` | `Application.SessionStack` | Descriptive of the stack structure, pairs well with `Current` |
 | `Toplevel` class | Keep as-is (for now) | Too disruptive to rename; allow gradual evolution toward `IRunnable` |
 
 ## Why These Names?
@@ -22,9 +22,10 @@ This is a brief summary of the [full terminology proposal](terminology-proposal.
 - ✅ Short and memorable
 - ✅ Accurately describes the "currently active/running view"
 
-### Application.RunStack
-- ✅ Describes what it contains (running views)
+### Application.SessionStack
+- ✅ Describes what it contains (running sessions)
 - ✅ Describes its structure (stack)
+- ✅ Aligns with `SessionToken` terminology (consistency)
 - ✅ Works with future `IRunnable` interface
 - ✅ Clear relationship with `Current` (top of the stack)
 

docfx/docs/terminology-proposal.md

@@ -48,7 +48,7 @@ With the recent massive cleanup of legacy code (Issue #4374), Terminal.Gui v2's
 
 4. **No legacy baggage**: Unlike before, there are no legacy MainLoop or old Driver APIs to worry about - the codebase is clean and modern, making terminology updates easier.
 
-5. **Consistency with modern patterns**: The cleaned-up codebase now follows modern .NET patterns more closely - `Application.Current` and `Application.RunStack` would complete this modernization.
+5. **Consistency with modern patterns**: The cleaned-up codebase now follows modern .NET patterns more closely - `Application.Current` and `Application.SessionStack` would complete this modernization.
 
 ## Proposed Terminology
 
@@ -67,12 +67,13 @@ With the recent massive cleanup of legacy code (Issue #4374), Terminal.Gui v2's
 - `Application.Main` - Misleading, as it's not always the main/first view
 - `Application.CurrentRunnable` - Too verbose, assumes future IRunnable
 
-### 2. Application.TopLevels → Application.RunStack
+### 2. Application.TopLevels → Application.SessionStack
 
 **Rationale:**
-- **Descriptive**: Clearly indicates it's a stack of running views
+- **Descriptive**: Clearly indicates it's a stack of running sessions
 - **Technical**: Accurately represents the ConcurrentStack<T> implementation
-- **Paired**: Works well with `Application.Current` (Current from RunStack)
+- **Paired**: Works well with `Application.Current` (Current from SessionStack)
+- **Consistent**: Aligns with `SessionToken` terminology (renamed from `RunState` in Nov 2025)
 - **Future-proof**: Works whether items are `Toplevel` or `IRunnable`
 - **NOW PUBLIC** (Nov 2025): `TopLevels` was changed from internal to public, making its confusing name a **user-facing problem** that needs fixing
 
@@ -80,13 +81,15 @@ With the recent massive cleanup of legacy code (Issue #4374), Terminal.Gui v2's
 - With `TopLevels` now public (as of November 2025), its confusing name directly impacts users
 - The rename would improve the public API without breaking existing code (via deprecation)
 - Completes the modernization pattern started with `RunState` → `SessionToken`
+- `SessionStack` follows the same terminology pattern as `SessionToken`
 
 **Alternative Names Considered:**
 - `Application.ViewStack` - Too generic, not all views are in this stack
 - `Application.RunnableStack` - Assumes future IRunnable interface
 - `Application.ModalStack` - Inaccurate, non-modal views can be in the stack
 - `Application.ActiveViews` - Doesn't convey the stack nature
-- `Application.Sessions` - Less clear about the stack nature
+- `Application.Sessions` - Less clear about the stack nature; doesn't indicate the collection type
+- `Application.RunStack` - Previous proposal; doesn't align with SessionToken terminology
 
 ### 3. Toplevel Class → (Keep as-is with evolution plan)
 
@@ -121,7 +124,7 @@ public static partial class Application
     // NEW: Current API
     /// <summary>
     /// Gets the currently active view with its own run loop.
-    /// This is the view at the top of the <see cref="RunStack"/>.
+    /// This is the view at the top of the <see cref="SessionStack"/>.
     /// </summary>
     /// <remarks>
     /// The current view receives all keyboard and mouse input and is responsible
@@ -142,16 +145,16 @@ public static partial class Application
         internal set => ApplicationImpl.Instance.Top = value;
     }
 
-    // NEW: RunStack API
+    // NEW: SessionStack API
     /// <summary>
     /// Gets the stack of all currently running views.
     /// Views are pushed onto this stack when <see cref="Run(Toplevel, Func{Exception, bool})"/> 
     /// is called and popped when <see cref="RequestStop(Toplevel)"/> is called.
     /// </summary>
-    internal static ConcurrentStack<Toplevel> RunStack => TopLevels;
+    internal static ConcurrentStack<Toplevel> SessionStack => TopLevels;
 
     // DEPRECATED: Keep for backward compatibility
-    [Obsolete("Use Application.RunStack instead. This property will be removed in a future version.", false)]
+    [Obsolete("Use Application.SessionStack instead. This property will be removed in a future version.", false)]
     internal static ConcurrentStack<Toplevel> TopLevels => ApplicationImpl.Instance.TopLevels;
 }
 ```
@@ -165,7 +168,7 @@ public static partial class Application
 
 ### Phase 3: Internal Refactoring (No API Changes)
 
-- Update internal code to use `Application.Current` and `Application.RunStack`
+- Update internal code to use `Application.Current` and `Application.SessionStack`
 - Keep old properties as simple forwards for compatibility
 - Update test code to use new APIs
 
@@ -210,9 +213,9 @@ if (Application.TopLevels.Count > 0)
 }
 
 // New Code (when internal API is made public)
-if (Application.RunStack.Count > 0)
+if (Application.SessionStack.Count > 0)
 {
-    foreach (Toplevel runnable in Application.RunStack)
+    foreach (Toplevel runnable in Application.SessionStack)
     {
         // process each running view
     }
@@ -223,7 +226,7 @@ if (Application.RunStack.Count > 0)
 
 ### 1. Improved Clarity
 - `Application.Current` is immediately understandable
-- `RunStack` clearly describes what it is and what it contains
+- `SessionStack` clearly describes what it is and what it contains
 - Reduces cognitive load for new developers
 
 ### 2. Better Code Readability
@@ -242,7 +245,7 @@ Application.Current?.DoSomething();
 ### 4. Future-Proof
 - Works with planned `IRunnable` interface
 - `Current` can return `IRunnable?` in the future
-- `RunStack` can become `ConcurrentStack<IRunnable>` in the future
+- `SessionStack` can become `ConcurrentStack<IRunnable>` in the future
 
 ### 5. Minimal Breaking Changes
 - Deprecated APIs remain functional
@@ -275,7 +278,7 @@ Application.Current?.DoSomething();
 ### Core API Changes
 - [ ] Add `Application.Current` property with forwarding to `Top`
 - [ ] Add `[Obsolete]` attribute to `Application.Top` (warning disabled initially)
-- [ ] Add `Application.RunStack` property with forwarding to `TopLevels`
+- [ ] Add `Application.SessionStack` property with forwarding to `TopLevels`
 - [ ] Add `[Obsolete]` attribute to `Application.TopLevels` (warning disabled initially)
 - [ ] Update XML documentation for new properties
 - [ ] Update IApplication interface if needed
@@ -290,7 +293,7 @@ Application.Current?.DoSomething();
 
 ### Code Updates
 - [ ] Update all internal code to use `Application.Current`
-- [ ] Update all internal code to use `Application.RunStack` (where appropriate)
+- [ ] Update all internal code to use `Application.SessionStack` (where appropriate)
 - [ ] Update test code to use new APIs
 - [ ] Update example applications (UICatalog, Example, etc.)
 
@@ -332,7 +335,7 @@ Application.Current?.DoSomething();
 
 This proposal recommends:
 1. **Rename `Application.Top` → `Application.Current`**: Clear, concise, familiar
-2. **Rename `Application.TopLevels` → `Application.RunStack`**: Descriptive and accurate
+2. **Rename `Application.TopLevels` → `Application.SessionStack`**: Descriptive and accurate
 3. **Keep `Toplevel` class as-is**: Allow for gradual evolution toward `IRunnable`
 4. **Phased migration**: Maintain backward compatibility with clear deprecation path