Add Glfw3 windowing

.scripts/Setup.ps1

@@ -71,6 +71,22 @@ $projectsList = @(
         )
         PromptIgnore = $false
         Depends = @("Arcane")
+    },
+    @{
+        Module = "Crystal"
+        Projects = @(
+            @{ Folder = "Modules/Crystal"; Name = "CatalystUI.Modules.Crystal.Core" }
+        )
+        PromptIgnore = $false
+        Depends = @("Core")
+    },
+    @{
+        Module = "Crystal.Glfw3"
+        Projects = @(
+            @{ Folder = "Modules/Crystal"; Name = "CatalystUI.Modules.Crystal.Glfw3" }
+        )
+        PromptIgnore = $false
+        Depends = @("Crystal")
     }
 )
 

CatalystUI/CatalystUI.sln

@@ -36,6 +36,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CatalystUI.Modules.Arcane.I
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CatalystUI.Modules.Arcane.Core", "Modules\Arcane\CatalystUI.Modules.Arcane.Core\CatalystUI.Modules.Arcane.Core.csproj", "{047744B0-87DC-4808-99C4-5AC1F8A1EB4D}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CatalystUI.Modules.Crystal.Core", "Modules\Crystal\CatalystUI.Modules.Crystal.Core\CatalystUI.Modules.Crystal.Core.csproj", "{4DE1A1EB-103B-4E07-859A-354908ACE0E2}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CatalystUI.Modules.Crystal.Glfw3", "Modules\Crystal\CatalystUI.Modules.Crystal.Glfw3\CatalystUI.Modules.Crystal.Glfw3.csproj", "{BC5802D1-4C3E-4FD6-9E3B-9ED82CCB2D18}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -90,6 +94,14 @@ Global
 		{047744B0-87DC-4808-99C4-5AC1F8A1EB4D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{047744B0-87DC-4808-99C4-5AC1F8A1EB4D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{047744B0-87DC-4808-99C4-5AC1F8A1EB4D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{4DE1A1EB-103B-4E07-859A-354908ACE0E2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{4DE1A1EB-103B-4E07-859A-354908ACE0E2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{4DE1A1EB-103B-4E07-859A-354908ACE0E2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{4DE1A1EB-103B-4E07-859A-354908ACE0E2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{BC5802D1-4C3E-4FD6-9E3B-9ED82CCB2D18}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{BC5802D1-4C3E-4FD6-9E3B-9ED82CCB2D18}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{BC5802D1-4C3E-4FD6-9E3B-9ED82CCB2D18}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{BC5802D1-4C3E-4FD6-9E3B-9ED82CCB2D18}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{68F496AC-9438-40F1-9DF8-97363033D661} = {7EC51871-49A8-4991-BDAF-F43A4E9B8C9D}
@@ -107,5 +119,7 @@ Global
 		{0E1F2B64-37D9-4C24-9CED-9A44D7CDBB8C} = {9C3F6A00-82F5-4900-9D6C-07ACBBAAE823}
 		{C02600D7-087B-4190-9B47-F15184C19B2D} = {C8B02B42-826B-4EDE-B72F-F4F97C1A088D}
 		{047744B0-87DC-4808-99C4-5AC1F8A1EB4D} = {C8B02B42-826B-4EDE-B72F-F4F97C1A088D}
+		{4DE1A1EB-103B-4E07-859A-354908ACE0E2} = {41BEF490-7005-4D10-9958-22D636F9DE38}
+		{BC5802D1-4C3E-4FD6-9E3B-9ED82CCB2D18} = {41BEF490-7005-4D10-9958-22D636F9DE38}
 	EndGlobalSection
 EndGlobal

CatalystUI/Core/CatalystUI.Core/CatalystApp.cs

@@ -9,6 +9,7 @@
 // For full terms, see the LICENSE and NOTICE files in the project root.
 // -------------------------------------------------------------------------------------------------
 
+using Catalyst.Builders;
 using Catalyst.Debugging;
 using Catalyst.Threading;
 using System;

CatalystUI/Core/CatalystUI.Core/Connectors/IDataConnector.cs

@@ -17,8 +17,15 @@ namespace Catalyst.Connectors {
     /// <summary>
     /// Represents the data connector in the CatalystUI model.
     /// </summary>
+    /// <remarks>
+    /// The <see cref="IDataConnector{TLayerLow,TLayerHigh}"/> and <see cref="INativeConnector{TLayerLow,TLayerHigh}"/>
+    /// are the only two connectors that contain a layer without an associated layer restriction. For the native
+    /// connector, this is typically the higher layer, since various model layers may interact with the native
+    /// level of the system. Similarly, the data connector generally has a lower layer without restrictions, as
+    /// various model layers may need to interact with raw data sources.
+    /// </remarks>
     /// <inheritdoc cref="IConnector{TLayerLow,TLayerHigh}"/>
-    public interface IDataConnector<out TLayerLow, out TLayerHigh> : IConnector<TLayerLow, TLayerHigh> where TLayerLow : ISemanticsLayer<IDomain> where TLayerHigh : IDataLayer<IDomain> {
+    public interface IDataConnector<out TLayerLow, out TLayerHigh> : IConnector<TLayerLow, TLayerHigh> where TLayerLow : ILayer<IDomain> where TLayerHigh : IDataLayer<IDomain> {
 
         // ...
 

CatalystUI/Core/CatalystUI.Core/Connectors/INativeConnector.cs

@@ -17,8 +17,15 @@ namespace Catalyst.Connectors {
     /// <summary>
     /// Represents the native connector in the CatalystUI model.
     /// </summary>
+    /// <remarks>
+    /// The <see cref="IDataConnector{TLayerLow,TLayerHigh}"/> and <see cref="INativeConnector{TLayerLow,TLayerHigh}"/>
+    /// are the only two connectors that contain a layer without an associated layer restriction. For the native
+    /// connector, this is typically the higher layer, since various model layers may interact with the native
+    /// level of the system. Similarly, the data connector generally has a lower layer without restrictions, as
+    /// various model layers may need to interact with raw data sources.
+    /// </remarks>
     /// <inheritdoc cref="IConnector{TLayerLow,TLayerHigh}"/>
-    public interface INativeConnector<out TLayerLow, out TLayerHigh> : IConnector<TLayerLow, TLayerHigh> where TLayerLow : ISystemLayer<IDomain> where TLayerHigh : IWindowLayer<IDomain> {
+    public interface INativeConnector<out TLayerLow, out TLayerHigh> : IConnector<TLayerLow, TLayerHigh> where TLayerLow : ISystemLayer<IDomain> where TLayerHigh : ILayer<IDomain> {
 
         // ...
 

CatalystUI/Core/CatalystUI.Core/Debugging/DebugContext.cs

@@ -84,8 +84,8 @@ public void LogFatal(string message, params object[] args) {
         /// Logs an error with the specified message and optional arguments.
         /// </summary>
         /// <remarks>
-        /// If an exception is provided as an argument, the exception's <see cref="Exception.StackTrace"/> will be included in the log output.
-        /// If the message is null or empty, it will be replaced with the exception's <see cref="Exception.Message"/>
+        /// If an exception is provided as an argument, the exception's <see cref="System.Exception.StackTrace"/> will be included in the log output.
+        /// If the message is null or empty, it will be replaced with the exception's <see cref="System.Exception.Message"/>
         /// </remarks>
         /// <inheritdoc cref="Log(LogLevel, string, string?, object[])"/>
         [Conditional("DEBUG")]

CatalystUI/Core/CatalystUI.Core/IOptions.cs

@@ -0,0 +1,23 @@
+// -------------------------------------------------------------------------------------------------
+// CatalystUI Framework for .NET Core - https://catalystui.org/
+// Copyright (c) 2025 CatalystUI LLC. All rights reserved.
+// 
+// This file is part of CatalystUI and is provided as part of an early-access release.
+// Unauthorized commercial use, distribution, or modification is strictly prohibited.
+// 
+// This software is not open source and is not publicly licensed.
+// For full terms, see the LICENSE and NOTICE files in the project root.
+// -------------------------------------------------------------------------------------------------
+
+namespace Catalyst {
+
+    /// <summary>
+    /// Represents some form of constructor or configuration options.
+    /// </summary>
+    public interface IOptions {
+
+        // ...
+
+    }
+
+}

CatalystUI/Core/CatalystUI.Core/ModelRegistry.cs

@@ -15,9 +15,8 @@
 using Catalyst.Layers;
 using System;
 using System.Collections.Generic;
-using System.Threading;
 using System.Linq;
-
+using System.Threading;
 using LayerSet = System.Collections.Generic.HashSet<Catalyst.Layers.ILayer<Catalyst.Domains.IDomain>>;
 using LayerMap = System.Collections.Generic.Dictionary<System.Type, System.Collections.Generic.HashSet<Catalyst.Layers.ILayer<Catalyst.Domains.IDomain>>>;
 using DomainMap = System.Collections.Generic.Dictionary<System.Type, System.Collections.Generic.Dictionary<System.Type, System.Collections.Generic.HashSet<Catalyst.Layers.ILayer<Catalyst.Domains.IDomain>>>>;

CatalystUI/Core/CatalystUI.Core/Native/INativeApi.cs

@@ -9,6 +9,7 @@
 // For full terms, see the LICENSE and NOTICE files in the project root.
 // -------------------------------------------------------------------------------------------------
 
+using Catalyst.Threading;
 using System;
 
 namespace Catalyst.Native {
@@ -29,8 +30,30 @@ public interface INativeApi<out TSelf, out TApi> : IDisposable where TSelf : INa
         /// <summary>
         /// Requests an instance of the API.
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// When requesting with a custom dispatcher,
+        /// upon first initialization, the API will
+        /// be associated with the provided dispatcher.
+        /// Subsequent requests with a different dispatcher
+        /// will be ignored, and the originally associated
+        /// dispatcher will be used.
+        /// </para>
+        /// </remarks>
+        /// <example>
+        /// If an API instance is initialized on the main thread,
+        /// and then requested from a background thread with a custom dispatcher,
+        /// the main thread dispatcher will be used for all operations.
+        /// As a result, some APIs may respond poorly to cross-thread
+        /// communication if they are not designed for it (such as OpenGL,
+        /// which requires a context to be current on the thread it is used on).
+        /// Always ensure to request the API instance on the thread it was
+        /// originally initialized on, or use a custom dispatcher
+        /// appropriate to the API's threading model.
+        /// </example>
+        /// <param name="dispatcher">A thread dispatcher to associate with the API instance, or <see langword="null"/> to use a captured main thread dispatcher.</param>
         /// <returns>The instance of the API.</returns>
-        static abstract TSelf GetInstance();
+        static abstract TSelf GetInstance(ThreadDelegateDispatcher? dispatcher = null);
 
     }
 

CatalystUI/Core/CatalystUI.Debug/CatalystSerilogDebug.cs

@@ -71,22 +71,22 @@ private static void ConfigureLogger() {
             // Add an async sink
             config.WriteTo.Async(writeTo => {
                 // Create the logging template
-                string levelmap = @"
+                const string levelMap = """
                     if @l = 'Verbose' then 'VERBOSE'
                     else if @l = 'Debug' then 'DEBUG'
                     else if @l = 'Information' then 'INFO'
                     else if @l = 'Warning' then 'WARN'
                     else if @l = 'Error' then 'ERROR'
                     else if @l = 'Fatal' then 'CRITICAL'
                     else 'UNKNOWN'
-                ";
-                string thread = $@"
+                """;
+                string thread = $"""
                     if ThreadName is not null then ThreadName
                     else if ThreadId = {Environment.CurrentManagedThreadId} then 'MainThread'
                     else Concat('Thread ', ToString(ThreadId))
-                ";
+                """;
                 string threadTemplate = CatalystDebug.DebugOptions.ShowsThread ? "<{" + thread + "}> " : string.Empty;
-                string template = threadTemplate + "[{SourceContext}] [{@t:HH:mm:ss:fff}] [{" + levelmap + "}] {@m}{if @x is not null then '" + Environment.NewLine + "' + @x else ''}";
+                string template = threadTemplate + "[{SourceContext}] [{@t:HH:mm:ss:fff}] [{" + levelMap + "}] {@m}{if @x is not null then '" + Environment.NewLine + "' + @x else ''}";
                 ExpressionTemplate formatter = new(template + Environment.NewLine);
 
                 // Add a debug sink

CatalystUI/Core/CatalystUI.Debug/SerilogDebugContext.cs

@@ -57,8 +57,8 @@ public override void Log(LogLevel level, string message, string? prefix = null,
                         bool needsComma = false;
                         if (CatalystDebug.DebugOptions.ShowsFileName) {
                             string? file = frame.GetFileName();
-                            string? typeName = method.Name;
-                            string? assemblyName = method.DeclaringAssemblyName;
+                            string typeName = method.Name;
+                            string assemblyName = method.DeclaringAssemblyName;
                             sb.Append('<');
                             if (!string.IsNullOrEmpty(file)) {
                                 sb.Append(Path.GetFileName(file));
@@ -73,25 +73,18 @@ public override void Log(LogLevel level, string message, string? prefix = null,
                             needsComma = true;
                         }
                         if (CatalystDebug.DebugOptions.ShowsMethodName) {
-                            if (needsComma) {
-                                sb.Append('#');
-                            } else {
-                                sb.Append('<');
-                            }
+                            sb.Append(needsComma ? '#' : '<');
                             sb.Append(method.Name);
                             needsContinuation = true;
                             needsComma = true;
                         }
                         if (CatalystDebug.DebugOptions.ShowsLineNumber) {
-                            if (needsComma) {
-                                sb.Append('(');
-                            } else {
-                                sb.Append('<');
-                            }
+                            sb.Append(needsComma ? '(' : '<');
                             sb.Append(frame.GetFileLineNumber());
                             if (needsComma) sb.Append(')');
                             needsContinuation = true;
-                            needsComma = true;
+                            // ReSharper disable once RedundantAssignment
+                            needsComma = true; // in case more options are added later
                         }
                         if (needsContinuation) {
                             sb.Append('>').Append(' ');
@@ -101,6 +94,9 @@ public override void Log(LogLevel level, string message, string? prefix = null,
             } catch {
                 // not supported probably
             }
+            if (!string.IsNullOrWhiteSpace(prefix)) {
+                sb.Append('[').Append(prefix).Append(']').Append(' '); // prefix   
+            }
             sb.Append(message).Append(' ');
             if (args.Length > 0) {
                 if (args[0] is Exception e) {
@@ -113,7 +109,7 @@ public override void Log(LogLevel level, string message, string? prefix = null,
                     }
                 } else {
                     for (int i = 0; i < args.Length; i++) {
-                        sb.Append(args[i]?.ToString());
+                        sb.Append(args[i]);
                         if (i < args.Length - 1) {
                             sb.Append(' ');
                         }