Add comprehensive Application.Run terminology proposal documents

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

TERMINOLOGY_INDUSTRY_COMPARISON.md

@@ -0,0 +1,291 @@
+# Application.Run Terminology - Industry Comparison
+
+This document compares Terminal.Gui's terminology with other popular UI frameworks to provide context for the proposed changes.
+
+## Framework Comparison Matrix
+
+### Complete Lifecycle (Show/Run a Window)
+
+| Framework | API | Notes |
+|-----------|-----|-------|
+| **Terminal.Gui (current)** | `Application.Run(toplevel)` | Modal execution |
+| **Terminal.Gui (proposed)** | `Application.Run(toplevel)` | Keep same (high-level API) |
+| **WPF** | `window.ShowDialog()` | Modal, returns DialogResult |
+| **WPF** | `window.Show()` | Non-modal |
+| **WinForms** | `form.ShowDialog()` | Modal |
+| **WinForms** | `Application.Run(form)` | Main message loop |
+| **Avalonia** | `window.ShowDialog()` | Modal, async |
+| **GTK#** | `window.ShowAll()` + `Gtk.Application.Run()` | Combined |
+| **Qt** | `QApplication::exec()` | Main event loop |
+| **Electron** | `mainWindow.show()` | Non-modal |
+
+### Session/Context Token
+
+| Framework | Concept | Type | Purpose |
+|-----------|---------|------|---------|
+| **Terminal.Gui (current)** | `RunState` | Class | Token for Begin/End pairing |
+| **Terminal.Gui (proposed)** | `ToplevelSession` | Class | Session token (clearer name) |
+| **WPF** | N/A | - | Hidden by framework |
+| **WinForms** | `ApplicationContext` | Class | Message loop context |
+| **Avalonia** | N/A | - | Hidden by framework |
+| **ASP.NET** | `HttpContext` | Class | Request context (analogous) |
+| **Entity Framework** | `DbContext` | Class | Session context (analogous) |
+
+**Analysis:** "Session" or "Context" are industry standards for bounded execution periods. "State" is misleading.
+
+### Initialize/Start
+
+| Framework | API | Purpose |
+|-----------|-----|---------|
+| **Terminal.Gui (current)** | `Application.Begin(toplevel)` | Prepare toplevel for execution |
+| **Terminal.Gui (proposed)** | `Application.BeginSession(toplevel)` | Start an execution session |
+| **WPF** | `window.Show()` / `window.ShowDialog()` | Combined with event loop |
+| **WinForms** | `Application.Run(form)` | Combined initialization |
+| **Node.js HTTP** | `server.listen()` | Start accepting requests |
+| **ASP.NET** | `app.Run()` | Start web server |
+| **Qt** | `widget->show()` | Show widget |
+
+**Analysis:** Most frameworks combine initialization with execution. Terminal.Gui's separation is powerful for advanced scenarios.
+
+### Event Loop Processing
+
+| Framework | API | Purpose | Notes |
+|-----------|-----|---------|-------|
+| **Terminal.Gui (current)** | `Application.RunLoop(runState)` | Process events until stopped | Confusing "Run" + "Loop" |
+| **Terminal.Gui (proposed)** | `Application.ProcessEvents(session)` | Process events until stopped | Clear action verb |
+| **WPF** | `Dispatcher.Run()` | Run dispatcher loop | Hidden in most apps |
+| **WinForms** | `Application.Run()` | Process message loop | Auto-started |
+| **Node.js** | `eventLoop.run()` | Run event loop | Internal |
+| **Qt** | `QApplication::exec()` | Execute event loop | "exec" = execute |
+| **GTK** | `Gtk.Application.Run()` | Main loop | Standard GTK term |
+| **Win32** | `GetMessage()` / `DispatchMessage()` | Message pump | Manual control |
+| **X11** | `XNextEvent()` | Process events | Manual control |
+
+**Analysis:** "ProcessEvents" or "EventLoop" are clearer than "RunLoop". The term "pump" is Windows-specific.
+
+### Single Iteration
+
+| Framework | API | Purpose |
+|-----------|-----|---------|
+| **Terminal.Gui (current)** | `Application.RunIteration()` | Process one event cycle |
+| **Terminal.Gui (proposed)** | `Application.ProcessEventsIteration()` | Process one event cycle |
+| **Game Engines (Unity)** | `Update()` / `Tick()` | One frame/tick |
+| **Game Engines (Unreal)** | `Tick(DeltaTime)` | One frame |
+| **WPF** | `Dispatcher.ProcessEvents()` | Process pending events |
+| **WinForms** | `Application.DoEvents()` | Process pending events |
+| **Node.js** | `setImmediate()` / `process.nextTick()` | Next event loop iteration |
+
+**Analysis:** "Iteration", "Tick", or "DoEvents" are all clear. "ProcessEvents" aligns with WPF.
+
+### Cleanup/End
+
+| Framework | API | Purpose |
+|-----------|-----|---------|
+| **Terminal.Gui (current)** | `Application.End(runState)` | Clean up after execution |
+| **Terminal.Gui (proposed)** | `Application.EndSession(session)` | End the execution session |
+| **WPF** | `window.Close()` | Close window |
+| **WinForms** | `form.Close()` | Close form |
+| **ASP.NET** | Request ends automatically | Dispose context |
+| **Entity Framework** | `context.Dispose()` | Dispose context |
+
+**Analysis:** "EndSession" pairs clearly with "BeginSession". "Close" works for windows but not for execution context.
+
+### Stop/Request Stop
+
+| Framework | API | Purpose |
+|-----------|-----|---------|
+| **Terminal.Gui (current)** | `Application.RequestStop()` | Signal loop to stop |
+| **Terminal.Gui (proposed)** | `Application.StopProcessingEvents()` | Stop event processing |
+| **WPF** | `window.Close()` | Close window, stops its loop |
+| **WinForms** | `Application.Exit()` | Exit application |
+| **Node.js** | `server.close()` | Stop accepting connections |
+| **CancellationToken** | `cancellationToken.Cancel()` | Request cancellation |
+
+**Analysis:** "RequestStop" is already clear. "StopProcessingEvents" is more explicit about what stops.
+
+## Terminology Patterns Across Industries
+
+### Game Development
+
+Game engines use clear, explicit terminology:
+
+```csharp
+// Unity pattern
+void Start() { }      // Initialize
+void Update() { }     // Per-frame update (tick)
+void OnDestroy() { }  // Cleanup
+
+// Typical game loop
+while (running)
+{
+    ProcessInput();
+    UpdateGameState();
+    Render();
+}
+```
+
+**Lesson:** Use explicit verbs that describe what happens each phase.
+
+### Web Development
+
+Web frameworks use session/context patterns:
+
+```csharp
+// ASP.NET Core
+public void Configure(IApplicationBuilder app)
+{
+    app.Run(async context =>  // HttpContext = request session
+    {
+        await context.Response.WriteAsync("Hello");
+    });
+}
+
+// Entity Framework
+using (var context = new DbContext())  // Session
+{
+    // Work with data
+}
+```
+
+**Lesson:** "Context" or "Session" for bounded execution periods is industry standard.
+
+### GUI Frameworks
+
+Desktop GUI frameworks separate showing from modal execution:
+
+```csharp
+// WPF pattern
+window.Show();              // Non-modal
+var result = window.ShowDialog();  // Modal (blocks)
+
+// Terminal.Gui (current - confusing)
+Application.Run(toplevel);  // Modal? Non-modal? Unclear
+
+// Terminal.Gui (proposed - clearer)
+Application.Run(toplevel);  // High-level: modal execution
+// OR low-level:
+var session = Application.BeginSession(toplevel);
+Application.ProcessEvents(session);
+Application.EndSession(session);
+```
+
+**Lesson:** Separate high-level convenience from low-level control.
+
+## Key Insights
+
+### 1. "Run" is Overloaded Everywhere
+
+Many frameworks have "Run" methods, but they mean different things:
+- **WPF**: `Application.Run()` - "run the entire application"
+- **WinForms**: `Application.Run(form)` - "run with this form as main"
+- **ASP.NET**: `app.Run()` - "start the web server"
+- **Terminal.Gui**: `Application.Run(toplevel)` - "run this toplevel modally"
+
+**Solution:** Keep high-level `Run()` for simplicity, but clarify low-level APIs.
+
+### 2. Session/Context Pattern is Standard
+
+The pattern of a token representing a bounded execution period is common:
+- `HttpContext` - one HTTP request
+- `DbContext` - one database session
+- `ExecutionContext` - one execution scope
+- `CancellationToken` - one cancellation scope
+
+**Terminal.Gui's `RunState` fits this pattern** - it should be named accordingly.
+
+### 3. Begin/End vs Start/Stop vs Open/Close
+
+Different frameworks use different pairs:
+- **Begin/End** - .NET (BeginInvoke/EndInvoke, BeginInit/EndInit)
+- **Start/Stop** - Common (StartService/StopService)
+- **Open/Close** - Resources (OpenFile/CloseFile, OpenConnection/CloseConnection)
+
+Terminal.Gui currently uses **Begin/End**, which is fine, but it needs a noun:
+- ✅ `BeginSession/EndSession` - Clear
+- ❓ `Begin/End` - Begin what?
+
+### 4. Event Processing Terminology
+
+Most frameworks use one of:
+- **ProcessEvents** - Explicit action (WPF, WinForms)
+- **EventLoop** - Noun describing the construct
+- **Pump/PumpMessages** - Windows-specific
+- **Dispatch** - Action of dispatching events
+
+**Terminal.Gui's "RunLoop"** is ambiguous - it could be a verb (run the loop) or a noun (the RunLoop object).
+
+## Recommendations Based on Industry Analysis
+
+### Primary Recommendation: Session-Based (Option 1)
+
+```
+Application.Run(toplevel)                              // Keep - familiar, simple
+  ├─ Application.BeginSession(toplevel) → ToplevelSession
+  ├─ Application.ProcessEvents(session)
+  └─ Application.EndSession(session)
+```
+
+**Aligns with:**
+- .NET patterns (BeginInvoke/EndInvoke, HttpContext sessions)
+- Industry standard "session" terminology
+- Explicit "ProcessEvents" from WPF/WinForms
+
+**Why it wins:**
+1. "Session" is universally understood as bounded execution
+2. "ProcessEvents" is explicit about what happens
+3. Begin/End is already .NET standard
+4. Minimal disruption to existing mental model
+
+### Alternative: Lifecycle-Based (Option 3)
+
+```
+Application.Run(toplevel)
+  ├─ Application.Start(toplevel) → ExecutionContext
+  ├─ Application.Execute(context)
+  └─ Application.Stop(context)
+```
+
+**Aligns with:**
+- Service patterns (StartService/StopService)
+- Game patterns (Start/Update/Stop)
+- Simpler verbs
+
+**Trade-offs:**
+- ⚠️ "Start/Stop" breaks existing Begin/End pattern
+- ✅ More intuitive for newcomers
+- ⚠️ "Execute" is less explicit than "ProcessEvents"
+
+### Why Not Modal/Show (Option 2)
+
+```
+Application.ShowModal(toplevel)
+  ├─ Application.Activate(toplevel)
+  └─ Application.Deactivate(toplevel)
+```
+
+**Issues:**
+- Terminal.Gui doesn't distinguish modal/non-modal the way WPF does
+- "Activate/Deactivate" implies window state, not execution
+- Bigger departure from current API
+
+## Conclusion
+
+**Industry analysis supports Option 1 (Session-Based):**
+
+1. ✅ "Session" is industry standard for bounded execution
+2. ✅ "ProcessEvents" is clear and matches WPF/WinForms
+3. ✅ Begin/End is established .NET pattern
+4. ✅ Minimal disruption to existing API
+5. ✅ Clear improvement over current "Run*" terminology
+
+The proposed terminology brings Terminal.Gui in line with industry patterns while respecting its unique architecture that exposes low-level event loop control.
+
+## References
+
+- [WPF Application Model](https://docs.microsoft.com/en-us/dotnet/desktop/wpf/app-development/application-management-overview)
+- [WinForms Application Class](https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.application)
+- [Avalonia Application Lifetime](https://docs.avaloniaui.net/docs/concepts/application-lifetimes)
+- [GTK Application](https://docs.gtk.org/gtk4/class.Application.html)
+- [Qt Application](https://doc.qt.io/qt-6/qapplication.html)
+- [.NET HttpContext](https://docs.microsoft.com/en-us/dotnet/api/system.web.httpcontext)
+- [Entity Framework DbContext](https://docs.microsoft.com/en-us/ef/core/dbcontext-configuration/)

TERMINOLOGY_PROPOSAL.md

@@ -0,0 +1,277 @@
+# Application.Run Terminology Proposal
+
+## Executive Summary
+
+This document proposes improved terminology for the Terminal.Gui application execution lifecycle. The current `Run` terminology is overloaded and confusing, encompassing multiple distinct concepts. This proposal introduces clearer, more precise naming that better communicates the purpose and relationships of each API.
+
+## Problem Statement
+
+The current terminology around `Application.Run` is confusing because:
+
+1. **"Run" is overloaded** - It refers to both:
+   - The complete lifecycle (Begin → RunLoop → End → Stop)
+   - The event loop itself (RunLoop)
+   - Multiple API methods (Run, RunLoop, RunIteration)
+
+2. **Relationships are unclear** - Users don't understand that:
+   - `Run()` is a convenience method = `Begin()` + `RunLoop()` + `End()`
+   - `RunState` is a session token, not a state object
+   - `RequestStop()` affects `RunLoop()` which triggers `End()`
+
+3. **Inconsistent with industry patterns** - Other frameworks use clearer terms:
+   - WPF: `Show()`, `ShowDialog()`, `Close()`
+   - WinForms: `Show()`, `ShowDialog()`, `Application.Run()`
+   - Avalonia: `Show()`, `ShowDialog()`, `StartWithClassicDesktopLifetime()`
+
+## Current Terminology Analysis
+
+### Current APIs and Their Actual Purposes
+
+| Current Name | Actual Purpose | Confusion Point |
+|-------------|----------------|-----------------|
+| `Run()` | Complete lifecycle: Begin + Loop + End | Overloaded - means too many things |
+| `RunState` | Session token/handle for a Toplevel execution | Sounds like state data, not a handle |
+| `Begin()` | Initialize and prepare a Toplevel for execution | "Begin" what? Begin running? |
+| `RunLoop()` | Execute the event loop until stopped | Clear, but tied to "Run" |
+| `RunIteration()` | Execute one iteration of the event loop | Clear |
+| `End()` | Clean up after a Toplevel execution session | "End" what? End running? |
+| `RequestStop()` | Signal the event loop to stop | What does it stop? |
+| `EndAfterFirstIteration` | Exit after one loop iteration | Tied to "End" but affects loop |
+
+### Current Flow
+
+```
+Application.Run(toplevel)
+  └─> Application.Begin(toplevel) → returns RunState
+      └─> Initialize
+      └─> Layout
+      └─> Draw
+  └─> Application.RunLoop(runState)
+      └─> while (Running)
+          └─> Application.RunIteration()
+              └─> Process events
+              └─> Layout (if needed)
+              └─> Draw (if needed)
+  └─> Application.End(runState)
+      └─> Clean up
+      └─> Dispose RunState
+```
+
+## Proposed Terminology
+
+### Option 1: Session-Based Terminology (Recommended)
+
+This option emphasizes that running a Toplevel is a "session" with clear lifecycle management.
+
+| Current | Proposed | Rationale |
+|---------|----------|-----------|
+| `Run()` | `Run()` | Keep for backward compatibility and familiarity |
+| `RunState` | `ToplevelSession` | Clear that it's a session token, not state |
+| `Begin()` | `BeginSession()` | Clear what is beginning |
+| `RunLoop()` | `ProcessEvents()` | Describes what it does, not abstract "run" |
+| `RunIteration()` | `ProcessEventsIteration()` | Consistent with ProcessEvents |
+| `End()` | `EndSession()` | Clear what is ending |
+| `RequestStop()` | `StopProcessingEvents()` | Clear what stops |
+| `EndAfterFirstIteration` | `StopAfterFirstIteration` | Consistent with Stop terminology |
+
+**Usage Example:**
+```csharp
+// High-level (unchanged)
+Application.Run(myWindow);
+
+// Low-level (new names)
+ToplevelSession session = Application.BeginSession(myWindow);
+Application.ProcessEvents(session);
+Application.EndSession(session);
+```
+
+### Option 2: Modal/Show Terminology
+
+This option aligns with WPF/WinForms patterns, emphasizing the modal/non-modal nature.
+
+| Current | Proposed | Rationale |
+|---------|----------|-----------|
+| `Run()` | `ShowModal()` or `Run()` | Emphasizes modal nature, or keep Run |
+| `RunState` | `ToplevelHandle` | It's a handle/token for the execution |
+| `Begin()` | `Activate()` | Activates the Toplevel for display |
+| `RunLoop()` | `EventLoop()` | Standard terminology |
+| `RunIteration()` | `ProcessEvents()` | Processes one iteration of events |
+| `End()` | `Deactivate()` | Deactivates the Toplevel |
+| `RequestStop()` | `Close()` or `RequestStop()` | Familiar to GUI developers |
+| `EndAfterFirstIteration` | `SingleIteration` | Mode rather than action |
+
+**Usage Example:**
+```csharp
+// High-level
+Application.ShowModal(myWindow);
+
+// Low-level
+ToplevelHandle handle = Application.Activate(myWindow);
+while (!stopped)
+    Application.ProcessEvents(handle);
+Application.Deactivate(handle);
+```
+
+### Option 3: Lifecycle Terminology
+
+This option uses explicit lifecycle phases.
+
+| Current | Proposed | Rationale |
+|---------|----------|-----------|
+| `Run()` | `Run()` | Keep for compatibility |
+| `RunState` | `ExecutionContext` | It's a context for execution |
+| `Begin()` | `Start()` | Lifecycle: Start → Execute → Stop |
+| `RunLoop()` | `Execute()` | The execution phase |
+| `RunIteration()` | `Tick()` | Common game/event loop term |
+| `End()` | `Stop()` | Lifecycle: Start → Execute → Stop |
+| `RequestStop()` | `RequestStop()` | Keep, it's clear |
+| `EndAfterFirstIteration` | `StopAfterFirstTick` | Consistent with Tick |
+
+**Usage Example:**
+```csharp
+// High-level (unchanged)
+Application.Run(myWindow);
+
+// Low-level
+ExecutionContext context = Application.Start(myWindow);
+Application.Execute(context);
+Application.Stop(context);
+```
+
+## Recommendation: Option 1 (Session-Based)
+
+**Recommended choice:** Option 1 - Session-Based Terminology
+
+**Reasons:**
+
+1. **Accuracy** - "Session" accurately describes what's happening: a bounded period of execution for a Toplevel
+2. **Clarity** - "BeginSession/EndSession" are unambiguous pairs
+3. **ProcessEvents** - Clearly communicates what the loop does
+4. **Minimal conceptual shift** - The pattern is still Begin/Loop/End, just clearer
+5. **Extensibility** - "Session" can encompass future session-related features
+
+**Migration Strategy:**
+
+1. **Phase 1: Add new APIs with Obsolete attributes on old ones**
+   ```csharp
+   [Obsolete("Use BeginSession instead")]
+   public static RunState Begin(Toplevel toplevel)
+   
+   public static ToplevelSession BeginSession(Toplevel toplevel)
+   ```
+
+2. **Phase 2: Update documentation to use new terminology**
+3. **Phase 3: Update examples to use new APIs**
+4. **Phase 4: After 2-3 releases, consider removing obsolete APIs**
+
+## Alternative Names Considered
+
+### For RunState/ToplevelSession
+- `ToplevelToken` - Too focused on the token aspect
+- `ToplevelHandle` - C/Win32 feel, less modern
+- `ExecutionSession` - Too generic
+- `ToplevelContext` - Could work, but "context" is overloaded in .NET
+- `ToplevelExecution` - Sounds like a verb, not a noun
+
+### For Begin/BeginSession
+- `StartSession` - Could work, but Begin/End is a common .NET pattern
+- `OpenSession` - Open/Close works but less common for this use
+- `InitializeSession` - Too long
+
+### For RunLoop/ProcessEvents
+- `EventLoop` - Good, but sounds like a noun not a verb
+- `PumpEvents` - Win32 terminology, might work
+- `HandleEvents` - Similar to ProcessEvents
+- `MainLoop` - Confusing with MainLoop class
+
+### For End/EndSession
+- `CloseSession` - Could work with OpenSession
+- `FinishSession` - Less common
+- `TerminateSession` - Too harsh/formal
+
+## Documentation Changes Required
+
+1. **API Documentation**
+   - Update XML docs for all affected methods
+   - Add clear examples showing lifecycle
+   - Document the relationship between high-level `Run()` and low-level session APIs
+
+2. **Conceptual Documentation**
+   - Create "Application Lifecycle" documentation page
+   - Add diagrams showing the flow
+   - Explain when to use `Run()` vs. low-level APIs
+
+3. **Migration Guide**
+   - Create mapping table (old → new)
+   - Provide before/after code examples
+   - Explain the rationale for changes
+
+## Implementation Notes
+
+### Backward Compatibility
+
+- All existing APIs remain functional
+- Mark old APIs with `[Obsolete]` attributes
+- Provide clear upgrade path in obsolete messages
+- Consider keeping old APIs indefinitely with internal delegation to new ones
+
+### Internal Implementation
+
+- New APIs can delegate to existing implementation
+- Gradually refactor internals to use new terminology
+- Update variable names and comments to use new terms
+
+### Testing
+
+- Keep all existing tests working
+- Add new tests using new terminology
+- Test obsolete warnings work correctly
+
+## Comparison with Other Frameworks
+
+| Framework | Show View | Modal | Event Loop | Close |
+|-----------|-----------|-------|------------|-------|
+| **WPF** | `Show()` | `ShowDialog()` | `Dispatcher.Run()` | `Close()` |
+| **WinForms** | `Show()` | `ShowDialog()` | `Application.Run()` | `Close()` |
+| **Avalonia** | `Show()` | `ShowDialog()` | `Start()` | `Close()` |
+| **GTK** | `show()` | `run()` | `main()` | `close()` |
+| **Terminal.Gui v2 (current)** | `Run()` | `Run()` | `RunLoop()` | `RequestStop()` |
+| **Terminal.Gui v2 (proposed)** | `Run()` | `Run()` | `ProcessEvents()` | `StopProcessingEvents()` |
+
+## FAQ
+
+**Q: Why not just keep "Run"?**
+A: "Run" is too overloaded. It doesn't distinguish between the complete lifecycle and the event loop, leading to confusion about what `RunLoop`, `RunState`, and `RunIteration` mean.
+
+**Q: Why "Session" instead of "Context" or "Handle"?**
+A: "Session" best captures the bounded execution period. "Context" is overloaded in .NET (DbContext, HttpContext, etc.). "Handle" is too low-level and platform-specific.
+
+**Q: What about breaking existing code?**
+A: We maintain complete backward compatibility by keeping old APIs and using `[Obsolete]` attributes. Users can migrate at their own pace.
+
+**Q: Is this bikeshedding?**
+A: No. Clear terminology is essential for framework usability. The current confusion around "Run" causes real problems for users learning the framework.
+
+**Q: Why not align exactly with WPF/WinForms?**
+A: Terminal.Gui has a different model - it exposes the event loop explicitly, which WPF/WinForms don't. We need terminology that fits our model while learning from established patterns.
+
+## Conclusion
+
+The proposed Session-Based terminology clarifies the Application execution lifecycle while maintaining backward compatibility. The new names are:
+
+- **More descriptive** - `ToplevelSession` vs `RunState`, `ProcessEvents` vs `RunLoop`
+- **More consistent** - `BeginSession`/`EndSession` pair, `ProcessEvents`/`StopProcessingEvents` pair
+- **More familiar** - Aligns with common patterns while respecting Terminal.Gui's unique architecture
+- **More maintainable** - Clear naming reduces cognitive load for contributors
+
+The migration path is straightforward, with minimal disruption to existing users.
+
+---
+
+## Next Steps
+
+1. **Community Feedback** - Gather feedback on this proposal from maintainers and community
+2. **Refinement** - Adjust terminology based on feedback
+3. **Implementation Plan** - Create detailed implementation plan with milestones
+4. **Documentation** - Prepare comprehensive documentation updates
+5. **Migration** - Implement changes with proper obsolete warnings and guidance

TERMINOLOGY_QUICK_REFERENCE.md

@@ -0,0 +1,258 @@
+# Application Run Terminology - Quick Reference
+
+## Current State (Confusing)
+
+```
+Application.Run(toplevel)
+  ├─ Application.Begin(toplevel) → RunState
+  ├─ Application.RunLoop(RunState)
+  │   └─ Application.RunIteration()
+  └─ Application.End(RunState)
+```
+
+**Problems:**
+- "Run" means too many things (lifecycle, loop, method names)
+- "RunState" sounds like state data, but it's a token
+- "Begin/End" - begin/end what?
+- "RunLoop" vs "RunIteration" - relationship unclear
+
+## Proposed (Clear) - Option 1: Session-Based ⭐
+
+```
+Application.Run(toplevel)  // High-level API (unchanged)
+  ├─ Application.BeginSession(toplevel) → ToplevelSession
+  ├─ Application.ProcessEvents(ToplevelSession)
+  │   └─ Application.ProcessEventsIteration()
+  └─ Application.EndSession(ToplevelSession)
+```
+
+**Benefits:**
+- "Session" clearly indicates bounded execution period
+- "ProcessEvents" describes what the loop does
+- "BeginSession/EndSession" are unambiguous pairs
+- "ToplevelSession" clearly indicates a session token
+
+## Proposed (Clear) - Option 2: Modal/Show
+
+```
+Application.ShowModal(toplevel)  // or keep Run()
+  ├─ Application.Activate(toplevel) → ToplevelHandle
+  ├─ Application.EventLoop(ToplevelHandle)
+  │   └─ Application.ProcessEvents()
+  └─ Application.Deactivate(ToplevelHandle)
+```
+
+**Benefits:**
+- Aligns with WPF/WinForms patterns
+- "Activate/Deactivate" are familiar GUI concepts
+- "EventLoop" is industry standard terminology
+
+## Proposed (Clear) - Option 3: Lifecycle
+
+```
+Application.Run(toplevel)
+  ├─ Application.Start(toplevel) → ExecutionContext
+  ├─ Application.Execute(ExecutionContext)
+  │   └─ Application.Tick()
+  └─ Application.Stop(ExecutionContext)
+```
+
+**Benefits:**
+- Explicit lifecycle phases (Start → Execute → Stop)
+- "Tick" is familiar from game development
+- Simple, clear verbs
+
+## Side-by-Side Comparison
+
+| Concept | Current | Option 1 (Session) ⭐ | Option 2 (Modal) | Option 3 (Lifecycle) |
+|---------|---------|---------------------|------------------|---------------------|
+| Complete lifecycle | `Run()` | `Run()` | `ShowModal()` or `Run()` | `Run()` |
+| Session token | `RunState` | `ToplevelSession` | `ToplevelHandle` | `ExecutionContext` |
+| Initialize | `Begin()` | `BeginSession()` | `Activate()` | `Start()` |
+| Event loop | `RunLoop()` | `ProcessEvents()` | `EventLoop()` | `Execute()` |
+| One iteration | `RunIteration()` | `ProcessEventsIteration()` | `ProcessEvents()` | `Tick()` |
+| Cleanup | `End()` | `EndSession()` | `Deactivate()` | `Stop()` |
+| Stop loop | `RequestStop()` | `StopProcessingEvents()` | `Close()` or `RequestStop()` | `RequestStop()` |
+| Stop mode flag | `EndAfterFirstIteration` | `StopAfterFirstIteration` | `SingleIteration` | `StopAfterFirstTick` |
+
+## Usage Examples
+
+### High-Level (All Options - Unchanged)
+
+```csharp
+// Simple case - most users use this
+Application.Init();
+Application.Run(myWindow);
+Application.Shutdown();
+```
+
+### Low-Level - Current (Confusing)
+
+```csharp
+Application.Init();
+
+RunState runState = Application.Begin(myWindow);  // Begin what?
+Application.RunLoop(runState);                     // Run vs RunLoop?
+Application.End(runState);                         // End what?
+
+Application.Shutdown();
+```
+
+### Low-Level - Option 1: Session-Based ⭐
+
+```csharp
+Application.Init();
+
+ToplevelSession session = Application.BeginSession(myWindow);  // Clear: starting a session
+Application.ProcessEvents(session);                             // Clear: processing events
+Application.EndSession(session);                                // Clear: ending the session
+
+Application.Shutdown();
+```
+
+### Low-Level - Option 2: Modal/Show
+
+```csharp
+Application.Init();
+
+ToplevelHandle handle = Application.Activate(myWindow);  // Clear: activating for display
+Application.EventLoop(handle);                           // Clear: running event loop
+Application.Deactivate(handle);                          // Clear: deactivating
+
+Application.Shutdown();
+```
+
+### Low-Level - Option 3: Lifecycle
+
+```csharp
+Application.Init();
+
+ExecutionContext context = Application.Start(myWindow);  // Clear: starting execution
+Application.Execute(context);                            // Clear: executing
+Application.Stop(context);                               // Clear: stopping
+
+Application.Shutdown();
+```
+
+## Manual Event Loop Control
+
+### Current (Confusing)
+
+```csharp
+RunState rs = Application.Begin(myWindow);
+Application.EndAfterFirstIteration = true;
+
+while (!done)
+{
+    Application.RunIteration(ref rs, firstIteration);  // What's RunIteration vs RunLoop?
+    firstIteration = false;
+    // Do custom processing...
+}
+
+Application.End(rs);
+```
+
+### Option 1: Session-Based (Clear) ⭐
+
+```csharp
+ToplevelSession session = Application.BeginSession(myWindow);
+Application.StopAfterFirstIteration = true;
+
+while (!done)
+{
+    Application.ProcessEventsIteration(ref session, firstIteration);  // Clear: process one iteration
+    firstIteration = false;
+    // Do custom processing...
+}
+
+Application.EndSession(session);
+```
+
+### Option 2: Modal/Show (Clear)
+
+```csharp
+ToplevelHandle handle = Application.Activate(myWindow);
+Application.SingleIteration = true;
+
+while (!done)
+{
+    Application.ProcessEvents(ref handle, firstIteration);  // Clear: process events
+    firstIteration = false;
+    // Do custom processing...
+}
+
+Application.Deactivate(handle);
+```
+
+### Option 3: Lifecycle (Clear)
+
+```csharp
+ExecutionContext context = Application.Start(myWindow);
+Application.StopAfterFirstTick = true;
+
+while (!done)
+{
+    Application.Tick(ref context, firstIteration);  // Clear: one tick
+    firstIteration = false;
+    // Do custom processing...
+}
+
+Application.Stop(context);
+```
+
+## Recommendation: Option 1 (Session-Based)
+
+**Why Session-Based wins:**
+1. ✅ Most accurate - "session" perfectly describes bounded execution
+2. ✅ Least disruptive - keeps Begin/End pattern, just clarifies it
+3. ✅ Most descriptive - "ProcessEvents" is clearer than "RunLoop"
+4. ✅ Industry standard - "session" is widely understood in software
+5. ✅ Extensible - easy to add session-related features later
+
+**Implementation:**
+- Add new APIs alongside existing ones
+- Mark old APIs `[Obsolete]` with helpful messages
+- Update docs to use new terminology
+- Maintain backward compatibility indefinitely
+
+## Related Concepts
+
+### Application Lifecycle
+
+```
+Application.Init()           // Initialize the application
+  ├─ Create driver
+  ├─ Setup screen
+  └─ Initialize subsystems
+
+Application.Run(toplevel)    // Run a toplevel (modal)
+  ├─ BeginSession
+  ├─ ProcessEvents
+  └─ EndSession
+
+Application.Shutdown()       // Shutdown the application
+  ├─ Cleanup resources
+  └─ Restore terminal
+```
+
+### Session vs Application Lifecycle
+
+| Application Lifecycle | Session Lifecycle |
+|----------------------|-------------------|
+| `Init()` - Once per app | `BeginSession()` - Per toplevel |
+| `Run()` - Can have multiple | `ProcessEvents()` - Within one session |
+| `Shutdown()` - Once per app | `EndSession()` - Per toplevel |
+
+## Events and Notifications
+
+| Current | Proposed (Option 1) |
+|---------|---------------------|
+| `NotifyNewRunState` | `NotifyNewSession` |
+| `NotifyStopRunState` | `NotifyStopSession` |
+| `RunStateEventArgs` | `ToplevelSessionEventArgs` |
+
+## See Also
+
+- [Full Proposal Document](TERMINOLOGY_PROPOSAL.md) - Detailed rationale and analysis
+- [Migration Guide](docs/migration-guide.md) - How to update your code (TODO)
+- [API Reference](docfx/api/Terminal.Gui.App.Application.yml) - API documentation