Add console sampler sample

Author: ph0rd

CHANGELOG.md

@@ -4,6 +4,6 @@
 
 - Prepare the first public NuGet package for `Ph0rd.ColorSampler`.
 - Add complete package metadata, README packaging, license metadata, and package icon.
-- Add WPF, WinForms, and WinUI 3 samples.
+- Add console, WPF, WinForms, and WinUI 3 samples.
 - Document the render-thread event contract and Windows-only implementation requirements.
 - Hide the normal, I-beam, and hand system cursors during sampling, then restore Windows defaults on stop, dispose, or process exit.

ColorSampler.sln

@@ -9,6 +9,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ColorSampler", "src\ColorSa
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{5D20AA90-6969-D8BD-9DCD-8634F4692FDA}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ColorSampler.ConsoleSample", "samples\ColorSampler.ConsoleSample\ColorSampler.ConsoleSample.csproj", "{D929E416-18E2-495D-8E54-3D5E176D5726}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ColorSampler.WpfSample", "samples\ColorSampler.WpfSample\ColorSampler.WpfSample.csproj", "{688CC018-38D6-4259-88E8-B340E7B533A8}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ColorSampler.WinFormsSample", "samples\ColorSampler.WinFormsSample\ColorSampler.WinFormsSample.csproj", "{A094AE0B-4F73-4E83-B605-46F88963A7F4}"
@@ -37,6 +39,18 @@ Global
 		{582E16AB-470E-496C-AFA0-3B9BEA06917D}.Release|x64.Build.0 = Release|Any CPU
 		{582E16AB-470E-496C-AFA0-3B9BEA06917D}.Release|x86.ActiveCfg = Release|Any CPU
 		{582E16AB-470E-496C-AFA0-3B9BEA06917D}.Release|x86.Build.0 = Release|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Debug|x64.Build.0 = Debug|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Debug|x86.Build.0 = Debug|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Release|x64.ActiveCfg = Release|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Release|x64.Build.0 = Release|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Release|x86.ActiveCfg = Release|Any CPU
+		{D929E416-18E2-495D-8E54-3D5E176D5726}.Release|x86.Build.0 = Release|Any CPU
 		{688CC018-38D6-4259-88E8-B340E7B533A8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{688CC018-38D6-4259-88E8-B340E7B533A8}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{688CC018-38D6-4259-88E8-B340E7B533A8}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -79,6 +93,7 @@ Global
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{582E16AB-470E-496C-AFA0-3B9BEA06917D} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{D929E416-18E2-495D-8E54-3D5E176D5726} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 		{688CC018-38D6-4259-88E8-B340E7B533A8} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 		{A094AE0B-4F73-4E83-B605-46F88963A7F4} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 		{24288966-857E-4D2A-B655-E57D958BCFA8} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}

ColorSampler.slnx

@@ -1,5 +1,6 @@
 <Solution>
   <Project Path="src/ColorSampler/ColorSampler.csproj" />
+  <Project Path="samples/ColorSampler.ConsoleSample/ColorSampler.ConsoleSample.csproj" />
   <Project Path="samples/ColorSampler.WpfSample/ColorSampler.WpfSample.csproj" />
   <Project Path="samples/ColorSampler.WinFormsSample/ColorSampler.WinFormsSample.csproj" />
   <Project Path="samples/ColorSampler.WinUISample/ColorSampler.WinUISample.csproj" />

README.md

@@ -1,6 +1,6 @@
 # Ph0rd.ColorSampler
 
-`Ph0rd.ColorSampler` is a performant Windows desktop eyedropper for .NET apps (WinUI 3, WPF, WinForms). 
+`Ph0rd.ColorSampler` is a performant Windows desktop eyedropper for .NET apps (WinUI 3, WPF, WinForms, console).
 It shows a click-through crosshair, a zoomed pixel preview, and raises simple events as the sampled color changes, is confirmed, or is cancelled.
 
 It is the color sampling component used by [Instant Syntax Styler](https://www.ph0rd.com/instant-syntax-styler/), the Visual Studio 2026 extension for changing syntax 
@@ -80,22 +80,28 @@ Supported target frameworks:
 
 Expected limitations:
 
-- It is not for web, service, console-only, macOS, or Linux apps.
+- It is not for web, service, macOS, or Linux apps.
+- Console apps are supported when they run in an interactive Windows desktop session.
 - Security tools, RDP sessions, UAC prompts, lock screens, or secure desktops may block or interrupt sampling.
 - The sampler captures normal desktop pixels. It is not designed to bypass protected content.
 
 ## Samples
 
-The repository includes three small samples:
+The repository includes four small samples:
 
 ```powershell
+dotnet run --project samples/ColorSampler.ConsoleSample/ColorSampler.ConsoleSample.csproj
 dotnet run --project samples/ColorSampler.WpfSample/ColorSampler.WpfSample.csproj
 dotnet run --project samples/ColorSampler.WinFormsSample/ColorSampler.WinFormsSample.csproj
 dotnet run --project samples/ColorSampler.WinUISample/ColorSampler.WinUISample.csproj
 ```
 
-Each sample shows the same pattern: create a `Sampler`, subscribe to `ColorChanged`, `Confirmed`, and `Cancelled`, 
-marshal back to the UI thread, and dispose the sampler when finished.
+The console sample is intentionally script-friendly: it launches sampling immediately, writes the confirmed
+color to stdout as `#RRGGBB`, returns exit code `0` when a color is selected, returns `1` when cancelled,
+and returns `2` for unexpected sampler errors.
+
+The GUI samples show the same UI pattern: create a `Sampler`, subscribe to `ColorChanged`, `Confirmed`,
+and `Cancelled`, marshal back to the UI thread, and dispose the sampler when finished.
 
 ## Build
 

docs/COLORSAMPLER_PUBLIC_RELEASE_PLAN.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Prepare `Ph0rd.ColorSampler` as a clean public GitHub repository and NuGet package. The repository should be understandable to a stranger, build from a clean clone, pack into a professional NuGet package, and include small WPF, WinForms, and WinUI 3 samples.
+Prepare `Ph0rd.ColorSampler` as a clean public GitHub repository and NuGet package. The repository should be understandable to a stranger, build from a clean clone, pack into a professional NuGet package, and include small console, WPF, WinForms, and WinUI 3 samples.
 
 ## Ground Rules
 
@@ -41,6 +41,7 @@ Prepare `Ph0rd.ColorSampler` as a clean public GitHub repository and NuGet packa
    - Document the render-thread event contract.
 
 3. Samples
+   - Console sample: immediate launch, one-line stdout output, and clear exit codes.
    - WPF sample: simple dispatcher-marshaled UI.
    - WinForms sample: simple `BeginInvoke` marshaling UI.
    - WinUI 3 sample: simple `DispatcherQueue` marshaling UI.
@@ -63,7 +64,7 @@ Prepare `Ph0rd.ColorSampler` as a clean public GitHub repository and NuGet packa
 - A pretty sample is worse than a tiny sample if it hides threading behavior.
 - The sampler owns a global mouse hook. Public docs must say concurrent sampling sessions are not supported.
 - The events fire off the UI thread. Every sample must demonstrate marshaling.
-- Do not add console, web, MAUI, Avalonia, or VS extension samples right now. They distract from the package.
+- Do not add web, MAUI, Avalonia, or VS extension samples right now. They distract from the package.
 - Do not claim macOS/Linux/browser support.
 - Publish only after maintainer review of the generated package and samples.
 
@@ -75,6 +76,7 @@ Prepare `Ph0rd.ColorSampler` as a clean public GitHub repository and NuGet packa
 - [x] README written for GitHub and NuGet.
 - [x] License and changelog added.
 - [x] Package icon added.
+- [x] Console sample added.
 - [x] WPF sample updated.
 - [x] WinForms sample added.
 - [x] WinUI 3 sample added.

docs/RELEASE_CHECKLIST.md

@@ -28,7 +28,7 @@ This repository is prepared for public release, but publishing must remain a del
    - `lib/net48/Ph0rd.ColorSampler.dll`
    - `lib/net8.0-windows7.0/Ph0rd.ColorSampler.dll`
 
-7. Run at least the WPF and WinForms samples locally.
+7. Run the console, WPF, and WinForms samples locally.
 8. Run the WinUI 3 sample locally if Windows App SDK tooling is installed.
 
 ## Publish

samples/ColorSampler.ConsoleSample/ColorSampler.ConsoleSample.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0-windows</TargetFramework>
+    <UseWPF>true</UseWPF>
+    <LangVersion>12</LangVersion>
+    <Nullable>enable</Nullable>
+    <RootNamespace>Ph0rd.ColorSampler.ConsoleSample</RootNamespace>
+    <AssemblyName>Ph0rd.ColorSampler.ConsoleSample</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\ColorSampler\ColorSampler.csproj" />
+  </ItemGroup>
+
+</Project>

samples/ColorSampler.ConsoleSample/Program.cs

@@ -0,0 +1,60 @@
+using Ph0rd.ColorSampler;
+
+using System;
+using System.Threading;
+
+var completed = new ManualResetEventSlim(false);
+var exitCode = 1;
+string? selectedColor = null;
+Exception? samplerError = null;
+
+using var sampler = new Sampler(onError: ex =>
+{
+    samplerError = ex;
+    exitCode = 2;
+    completed.Set();
+});
+
+sampler.Confirmed += color =>
+{
+    selectedColor = $"#{color.R:X2}{color.G:X2}{color.B:X2}";
+    exitCode = 0;
+    completed.Set();
+};
+
+sampler.Cancelled += () =>
+{
+    if (samplerError == null)
+        exitCode = 1;
+
+    completed.Set();
+};
+
+Console.CancelKeyPress += (_, e) =>
+{
+    e.Cancel = true;
+    sampler.Stop();
+};
+
+try
+{
+    sampler.Start();
+    completed.Wait();
+}
+catch (Exception ex)
+{
+    Console.Error.WriteLine(ex);
+    return 2;
+}
+finally
+{
+    sampler.Stop();
+}
+
+if (samplerError != null)
+    Console.Error.WriteLine(samplerError);
+
+if (exitCode == 0 && selectedColor != null)
+    Console.WriteLine(selectedColor);
+
+return exitCode;