Version 5.0.0

.github/workflows/UnitTests.yaml

@@ -13,13 +13,13 @@ jobs:
     uses: dusrdev/actions/.github/workflows/reusable-dotnet-test-mtp.yaml@main
     with:
       platform: ${{ matrix.platform }}
-      dotnet-version: 9.0.x
+      dotnet-version: 10.0.x
       test-project-path: PrettyConsole.Tests.Unit/PrettyConsole.Tests.Unit.csproj
 
   unit-tests-debug:
     uses: dusrdev/actions/.github/workflows/reusable-dotnet-test-mtp.yaml@main
     with:
       platform: ubuntu-latest
-      dotnet-version: 9.0.x
+      dotnet-version: 10.0.x
       test-project-path: PrettyConsole.Tests.Unit/PrettyConsole.Tests.Unit.csproj
       use-debug: true

.gitignore

@@ -64,7 +64,7 @@ nunit-*.xml
 dlldata.c
 
 # Benchmark Results
-BenchmarkDotNet.Artifacts/
+# BenchmarkDotNet.Artifacts/
 
 # .NET Core
 project.lock.json

AGENTS.md

@@ -4,11 +4,12 @@ Repository: PrettyConsole
 
 Summary
 
-- PrettyConsole is a high-performance, allocation-conscious wrapper over System.Console that provides structured colored output, input helpers, rendering controls, menus, and progress bars. It targets net9.0, is trimming/AOT ready, and ships SourceLink metadata for debugging.
+- PrettyConsole is a high-performance, allocation-conscious extension layer over System.Console (implemented via C# extension members) that provides structured colored output, input helpers, rendering controls, menus, and progress bars. It targets net10.0, is trimming/AOT ready, and ships SourceLink metadata for debugging.
 - Solution layout:
   - PrettyConsole/ — main library
   - PrettyConsole.Tests/ — interactive/demo runner (manually selects visual feature demos)
   - PrettyConsole.Tests.Unit/ — xUnit v3 unit tests using Microsoft Testing Platform
+- v5.0.0 (November 2025) removed the legacy `ColoredOutput`/`Color` types; color composition now flows through `ConsoleColor` helpers and tuples exposed by the library.
 
 Commands you’ll use often
 
@@ -43,28 +44,32 @@ Repo-specific agent rules and conventions
 High-level architecture and key concepts
 
 - Console facade
-  - `PrettyConsole.Console` is a static, partial wrapper over `System.Console`. It exposes the live `In`, `Out`, and `Error` streams, and adds helpers like `NewLine`, `Clear`, `ClearNextLines`, `GetCurrentLine`, `GoToLine`, `SetColors`, and `ResetColors` for structured rendering.
+  - Extension members declared via `extension(Console)` attach directly to `System.Console`, so APIs such as `Console.WriteInterpolated`, `Console.TryReadLine`, `Console.Overwrite`, etc. light up once `using PrettyConsole;` (optionally with `using static System.Console;`) is in scope. `PrettyConsoleExtensions` still exposes the live `In`, `Out`, and `Error` streams plus helpers like `GetWidthOrDefault`.
 - Output routing
-  - `OutputPipe` is a two-value enum (`Out`, `Error`). Most write APIs accept an optional pipe; internally `Console.GetWriter` resolves the correct `TextWriter` so sequences remain redirect-friendly.
+  - `OutputPipe` is a two-value enum (`Out`, `Error`). Most write APIs accept an optional pipe; internally `PrettyConsoleExtensions.GetWriter` resolves the correct `TextWriter` so sequences remain redirect-friendly.
 - Interpolated string handler
-  - `PrettyConsoleInterpolatedStringHandler` enables zero-allocation `$"..."` calls for `Write`, `WriteLine`, `ReadLine`, `TryReadLine`, `Confirm`, and `RequestAnyInput`. Colors automatically reset after each invocation, and handlers respect the selected pipe and optional `IFormatProvider`.
+  - `PrettyConsoleInterpolatedStringHandler` enables zero-allocation `$"..."` calls for `WriteInterpolated`, `WriteLineInterpolated`, `ReadLine`, `TryReadLine`, `Confirm`, and `RequestAnyInput`. Colors automatically reset after each invocation, and handlers respect the selected pipe and optional `IFormatProvider`. Recent changes ensure any `object` argument that implements `ISpanFormattable` is emitted through the span-based path before falling back to `IFormattable`/string allocations.
 - Coloring model
-  - `ColoredOutput` and the `Color` record provide terse composition via `"Text" * Color.Red / Color.Blue` and implicit conversions. Default foreground/background values are stored on `Color` so spans render without string allocations.
+  - `ConsoleColor` now exposes `DefaultForeground`, `DefaultBackground`, and `Default` tuple properties plus `/` operator overloads so you can inline foreground/background tuples (`$"{ConsoleColor.Red / ConsoleColor.White}Error"`). These tuples play nicely with the interpolated string handler and keep color resets allocation-free.
+- Markup decorations
+  - The `Markup` static class exposes ANSI sequences for underline, bold, italic, and strikethrough. Fields expand to escape codes only when output/error aren’t redirected; otherwise they collapse to empty strings so callers can safely interpolate them without extra checks.
 - Write APIs
-  - `Write`/`WriteLine` cover interpolated strings, `ColoredOutput` spans, raw `ReadOnlySpan<char>`, and generic `ISpanFormattable` values (including `ref struct`s) with optional foreground/background colors and format providers. Internally they rely on `BufferPool` to avoid allocation spikes.
+  - `WriteInterpolated`/`WriteLineInterpolated` host the interpolated-string handler; `Write`/`WriteLine` overloads target `ISpanFormattable` values (including `ref struct`s) and raw `ReadOnlySpan<char>` spans with optional foreground/background overrides. Implementations rent buffers via `BufferPool` to avoid allocation spikes and always reset colors.
+- TextWriter helpers
+  - `PrettyConsoleExtensions` surfaces a `TextWriter.WriteWhiteSpaces(int)` extension (available via `PrettyConsoleExtensions.Out/Error`) for allocation-free padding. Use it instead of creating temporary `string`s when building menus, tables, or progress output.
 - Inputs
   - `ReadLine`/`TryReadLine` support `IParsable<T>` types, optional defaults, enum parsing with `ignoreCase`, and interpolated prompts. `Confirm` exposes `DefaultConfirmValues`, overloads for custom truthy tokens, and interpolated prompts; `RequestAnyInput` blocks on `ReadKey` with colored prompts if desired.
 - Rendering controls
   - `ClearNextLines`, `GoToLine`, and `GetCurrentLine` coordinate bounded screen regions; `Clear` wipes the buffer when safe. These helpers underpin progress rendering and overwrite scenarios.
 - Advanced outputs
-  - `OverwriteCurrentLine`, `Overwrite`, and `Overwrite<TState>` run user actions while clearing a configurable number of lines, enabling reactive text dashboards without leaving artifacts. `TypeWrite`/`TypeWriteLine` animate character-by-character output with adjustable delays.
+  - `OverwriteCurrentLine`, `Overwrite`, and `Overwrite<TState>` run user actions while clearing a configurable number of lines. Set the `lines` argument to however many rows you emit during the action (e.g., the multi-progress sample uses `lines: 2`) and call `Console.ClearNextLines` once after the last overwrite to remove residual UI. `TypeWrite`/`TypeWriteLine` animate character-by-character output with adjustable delays.
 - Menus and tables
   - `Selection` returns a single choice or empty string on invalid input; `MultiSelection` parses space-separated indices into string arrays; `TreeMenu` renders two-level hierarchies and validates input (throwing `ArgumentException` when selections are invalid); `Table` renders headers + columns with width calculations.
 - Progress bars
   - `IndeterminateProgressBar` binds to running `Task` instances, optionally starts tasks, supports cancellable `RunAsync` overloads, exposes `AnimationSequence`, `Patterns`, `ForegroundColor`, `DisplayElapsedTime`, and `UpdateRate`. Frames render on the error pipe and auto-clear.
-  - `ProgressBar` maintains a single-line bar on the error pipe. `Update` accepts `int`/`double` percentages plus optional status spans, and exposes `ProgressChar`, `ForegroundColor`, and `ProgressColor` for customization.
+  - `ProgressBar` maintains a single-line bar on the error pipe. `Update` accepts `int`/`double` percentages plus optional status spans, and exposes `ProgressChar`, `ForegroundColor`, and `ProgressColor` for customization. The static `ProgressBar.WriteProgressBar` helper renders one-off segments without moving the cursor (so you can stack multiple bars within an `Overwrite` block).
 - Packaging and targets
-  - `PrettyConsole.csproj` targets net9.0, enables trimming/AOT (`IsTrimmable`, `IsAotCompatible`), embeds SourceLink, and grants `InternalsVisibleTo` the unit-test project.
+  - `PrettyConsole.csproj` targets net10.0, enables trimming/AOT (`IsTrimmable`, `IsAotCompatible`), embeds SourceLink, and grants `InternalsVisibleTo` the unit-test project.
 
 Testing structure and workflows
 
@@ -76,7 +81,8 @@ Testing structure and workflows
 
 Notes and gotchas
 
-- The library aims to minimize allocations; prefer span-based overloads (ReadOnlySpan<char>, ReadOnlySpan<ColoredOutput>) for best performance when contributing.
+- The library aims to minimize allocations; prefer span-based overloads (`ReadOnlySpan<char>`, `ISpanFormattable`) plus the inline `ConsoleColor` tuples instead of recreating strings or structs.
 - When authoring new features, pick the appropriate OutputPipe to keep CLI piping behavior intact.
 - On macOS terminals, ANSI is supported; Windows legacy terminals are handled via ANSI-compatible rendering in the library.
-- `ProgressBar.Update` re-renders on every call (even when the percentage is unchanged) and accepts `sameLine` to place the status above the bar; the static `ProgressBar.WriteProgressBar` renders one-off bars for multi-progress scenarios.
+- `ProgressBar.Update` re-renders on every call (even when the percentage is unchanged) and accepts `sameLine` to place the status above the bar; the static `ProgressBar.WriteProgressBar` renders one-off bars without writing a trailing newline, so rely on `Console.Overwrite`/`lines` to stack multiple bars cleanly.
+- After the final `Overwrite`/`Overwrite<TState>` call in a rendering loop, call `Console.ClearNextLines(totalLines, pipe)` once more to clear the region and prevent ghost text.

Benchmarks/BenchmarkDotNet.Artifacts/results/Benchmarks.StyledOutputBenchmarks-report-github.md

@@ -0,0 +1,17 @@
+```
+
+BenchmarkDotNet v0.15.6, macOS 26.1 (25B78) [Darwin 25.1.0]
+Apple M2 Pro, 1 CPU, 10 logical and 10 physical cores
+.NET SDK 10.0.100
+  [Host]     : .NET 10.0.0 (10.0.0, 10.0.25.52411), Arm64 RyuJIT armv8.0-a
+  Job-NEXDCO : .NET 10.0.0 (10.0.0, 10.0.25.52411), Arm64 RyuJIT armv8.0-a
+
+OutlierMode=RemoveAll  IterationCount=30  IterationTime=100ms  
+LaunchCount=3  WarmupCount=5  
+
+```
+| Method         | Mean        | Ratio         | Gen0   | Allocated | Alloc Ratio   |
+|--------------- |------------:|--------------:|-------:|----------:|--------------:|
+| PrettyConsole  |    95.02 ns | 49.73x faster |      - |         - |            NA |
+| SpectreConsole | 4,725.48 ns |      baseline | 2.0902 |   17840 B |               |
+| SystemConsole  |    68.67 ns | 68.81x faster | 0.0028 |      24 B | 743.333x less |

Benchmarks/Benchmarks.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="BenchmarkDotNet" Version="0.15.6" />
+    <PackageReference Include="Spectre.Console" Version="0.54.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../PrettyConsole/PrettyConsole.csproj" />
+  </ItemGroup>
+</Project>

Benchmarks/Config.cs

@@ -0,0 +1,69 @@
+using System.Collections.Immutable;
+
+using BenchmarkDotNet.Columns;
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Diagnosers;
+using BenchmarkDotNet.Exporters;
+using BenchmarkDotNet.Jobs;
+using BenchmarkDotNet.Loggers;
+using BenchmarkDotNet.Order;
+using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
+
+using Perfolizer.Horology;
+
+using Perfolizer.Mathematics.OutlierDetection;
+
+namespace Benchmarks;
+
+public class Config : ManualConfig {
+    public Config() {
+        UnionRule = ConfigUnionRule.AlwaysUseLocal;
+        SummaryStyle = SummaryStyle.Default.WithRatioStyle(RatioStyle.Trend);
+        AddDiagnoser(MemoryDiagnoser.Default);
+        AddJob(Job.Default
+            .WithOutlierMode(OutlierMode.RemoveAll)
+            .WithLaunchCount(3)
+            .WithWarmupCount(5)
+            .WithIterationCount(30)
+            .WithIterationTime(TimeInterval.FromMilliseconds(100)));
+        AddColumnProvider(DefaultColumnProviders.Instance);
+        HideColumns(Column.Error, Column.StdDev, Column.Median, Column.RatioSD);
+        WithOrderer(new GroupByTypeOrderer());
+        WithOptions(ConfigOptions.JoinSummary);
+        WithOptions(ConfigOptions.StopOnFirstError);
+        WithOptions(ConfigOptions.DisableLogFile);
+        AddExporter(MarkdownExporter.GitHub);
+        AddLogger(ConsoleLogger.Default);
+    }
+}
+
+internal sealed class GroupByTypeOrderer : IOrderer {
+    // Keep execution order as-declared (you can customize if you want)
+    public IEnumerable<BenchmarkCase> GetExecutionOrder(
+        ImmutableArray<BenchmarkCase> benchmarksCase,
+        IEnumerable<BenchmarkLogicalGroupRule>? order = null)
+        => benchmarksCase;
+
+    // Sort rows in the summary: first by Type, then Method, then Params
+    public IEnumerable<BenchmarkCase> GetSummaryOrder(
+        ImmutableArray<BenchmarkCase> cases, Summary summary) =>
+        cases.OrderBy(c => c.Descriptor.Type.FullName)
+             .ThenBy(c => c.Parameters.DisplayInfo);
+
+    // We don’t use highlight groups
+    public string? GetHighlightGroupKey(BenchmarkCase benchmarkCase) => null;
+
+    // Tell BDN how to “group” rows in a joined summary (the section separator)
+    public string GetLogicalGroupKey(
+        ImmutableArray<BenchmarkCase> all, BenchmarkCase benchmarkCase)
+        => benchmarkCase.Descriptor.Type.FullName!;
+
+    // Order the groups themselves (by class name)
+    public IEnumerable<IGrouping<string, BenchmarkCase>> GetLogicalGroupOrder(
+        IEnumerable<IGrouping<string, BenchmarkCase>> logicalGroups,
+        IEnumerable<BenchmarkLogicalGroupRule>? order = null)
+        => logicalGroups.OrderBy(g => g.Key);
+
+    public bool SeparateLogicalGroups => true;
+}

Benchmarks/Program.cs

@@ -0,0 +1,5 @@
+using BenchmarkDotNet.Running;
+
+using Benchmarks;
+
+BenchmarkRunner.Run<StyledOutputBenchmarks>();

Benchmarks/StyledOutputBenchmark.cs

@@ -0,0 +1,68 @@
+using BenchmarkDotNet.Attributes;
+
+using PrettyConsole;
+
+using Spectre.Console;
+
+using static System.ConsoleColor;
+
+namespace Benchmarks;
+
+/// <summary>
+/// Runs a benchmark printing the following output:
+/// Hello {Green}John{ResetColor}, status = {Cyan}{Percentage}{Reset}%, Elapsed = {Yellow}{Elapsed:c}{Reset}
+/// </summary>
+[Config(typeof(Config))]
+public class StyledOutputBenchmarks {
+    private static readonly TimeSpan Elapsed = new(1, 25, 31);
+    private const double Percentage = 57.91;
+
+    private TextWriter _outputWriter = default!;
+    private IAnsiConsole _ansiConsole = default!;
+
+    [GlobalSetup]
+    public void GlobalSetup() {
+        _outputWriter = Console.Out;
+        PrettyConsoleExtensions.Out = TextWriter.Null;
+        _ansiConsole = AnsiConsole.Create(new AnsiConsoleSettings {
+            Out = new AnsiConsoleOutput(TextWriter.Null)
+        });
+        Console.SetOut(TextWriter.Null);
+    }
+
+    [GlobalCleanup]
+    public void GlobalCleanup() {
+        PrettyConsoleExtensions.Out = _outputWriter;
+        _ansiConsole = AnsiConsole.Console;
+        Console.SetOut(_outputWriter);
+    }
+
+    [Benchmark]
+    public int PrettyConsole() {
+        Console.WriteLineInterpolated($"Hello {Green}John{ConsoleColor.DefaultForeground}, status = {Cyan}{Percentage}{ConsoleColor.DefaultForeground}%, elapsed = {Yellow}{Elapsed:c}");
+        return int.MaxValue;
+    }
+
+    [Benchmark(Baseline = true)]
+    public int SpectreConsole() {
+        _ansiConsole.MarkupLineInterpolated($"Hello [green]John[/], status = [cyan]{Percentage}[/]%, elapsed = [yellow]{Elapsed:c}[/]");
+        return int.MaxValue;
+    }
+
+    [Benchmark]
+    public int SystemConsole() {
+        Console.Write("Hello ");
+        Console.ForegroundColor = Green;
+        Console.Write("John");
+        Console.ResetColor();
+        Console.Write(", status = ");
+        Console.ForegroundColor = Cyan;
+        Console.Write(Percentage);
+        Console.ResetColor();
+        Console.Write("%, elapsed = ");
+        Console.ForegroundColor = Yellow;
+        Console.WriteLine("{0:c}", Elapsed);
+        Console.ResetColor();
+        return int.MaxValue;
+    }
+}