Hint system improvements and macOS CI test workflow

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: Build & Test
+
+on:
+  pull_request:
+    branches:
+      - main
+  merge_group:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  macos-unit-tests:
+    name: macOS Build & Test
+    runs-on: macos-26
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run unit tests (macOS)
+        run: |
+          xcodebuild test \
+            -project ComputerSolitaire.xcodeproj \
+            -scheme ComputerSolitaire \
+            -configuration Debug \
+            -destination "platform=macOS" \
+            -derivedDataPath "$RUNNER_TEMP/DerivedData" \
+            -resultBundlePath "$RUNNER_TEMP/ComputerSolitaireTests.xcresult" \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGNING_REQUIRED=NO
+
+      - name: Upload test result bundle on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-test-results
+          path: ${{ runner.temp }}/ComputerSolitaireTests.xcresult
+
+  ios-build:
+    name: iOS Build
+    runs-on: macos-26
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build app (iOS Simulator)
+        run: |
+          xcodebuild build \
+            -project ComputerSolitaire.xcodeproj \
+            -scheme ComputerSolitaire \
+            -configuration Debug \
+            -destination "generic/platform=iOS Simulator" \
+            -derivedDataPath "$RUNNER_TEMP/DerivedData" \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGNING_REQUIRED=NO

.gitignore

@@ -9,8 +9,9 @@ xcuserdata/
 ## Visual Studio Code
 .vscode
 
-## Build folder
+## Build artifacts
 build/
+.build/
 .derivedData/
 
 ## macOS custom folder icon

AGENTS.md

@@ -43,3 +43,31 @@ This file defines hard project constraints for any coding agent working in this
 - No speculative abstraction layers that make SwiftUI code harder to read.
 
 When in doubt, choose the simplest modern SwiftUI-first solution.
+
+## Build Workflow
+
+This command builds the macOS destination only.
+
+From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run:
+
+```bash
+/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild \
+  -project ComputerSolitaire.xcodeproj \
+  -scheme ComputerSolitaire \
+  -configuration Debug \
+  -destination 'generic/platform=macOS' \
+  build
+```
+
+## Test Workflow
+
+From repo root (`/Users/austinsmith/Developer/Repos/ComputerSolitaire`), run:
+
+```bash
+/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild \
+  -project ComputerSolitaire.xcodeproj \
+  -scheme ComputerSolitaire \
+  -configuration Debug \
+  -destination 'platform=macOS' \
+  test
+```

ComputerSolitaire.xcodeproj/project.pbxproj

@@ -6,8 +6,19 @@
 	objectVersion = 77;
 	objects = {
 
+/* Begin PBXContainerItemProxy section */
+		4B75C1EA2F1A233500761A12 /* PBXContainerItemProxy */ = {
+			isa = PBXContainerItemProxy;
+			containerPortal = 4B75C1C92F1A233400761A12 /* Project object */;
+			proxyType = 1;
+			remoteGlobalIDString = 4B75C1D02F1A233400761A12;
+			remoteInfo = ComputerSolitaire;
+		};
+/* End PBXContainerItemProxy section */
+
 /* Begin PBXFileReference section */
 		4B75C1D12F1A233400761A12 /* Computer Solitaire.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "Computer Solitaire.app"; sourceTree = BUILT_PRODUCTS_DIR; };
+		4B75C1E42F1A233500761A12 /* ComputerSolitaireTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = ComputerSolitaireTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
 
 /* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
@@ -29,6 +40,11 @@
 			path = ComputerSolitaire;
 			sourceTree = "<group>";
 		};
+		4B75C1E52F1A233500761A12 /* ComputerSolitaireTests */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = ComputerSolitaireTests;
+			sourceTree = "<group>";
+		};
 /* End PBXFileSystemSynchronizedRootGroup section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -39,13 +55,21 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		4B75C1E62F1A233500761A12 /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXFrameworksBuildPhase section */
 
 /* Begin PBXGroup section */
 		4B75C1C82F1A233400761A12 = {
 			isa = PBXGroup;
 			children = (
 				4B75C1D32F1A233400761A12 /* ComputerSolitaire */,
+				4B75C1E52F1A233500761A12 /* ComputerSolitaireTests */,
 				4B75C1D22F1A233400761A12 /* Products */,
 			);
 			sourceTree = "<group>";
@@ -54,6 +78,7 @@
 			isa = PBXGroup;
 			children = (
 				4B75C1D12F1A233400761A12 /* Computer Solitaire.app */,
+				4B75C1E42F1A233500761A12 /* ComputerSolitaireTests.xctest */,
 			);
 			name = Products;
 			sourceTree = "<group>";
@@ -83,6 +108,29 @@
 			productReference = 4B75C1D12F1A233400761A12 /* Computer Solitaire.app */;
 			productType = "com.apple.product-type.application";
 		};
+		4B75C1E92F1A233500761A12 /* ComputerSolitaireTests */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 4B75C1EC2F1A233500761A12 /* Build configuration list for PBXNativeTarget "ComputerSolitaireTests" */;
+			buildPhases = (
+				4B75C1E72F1A233500761A12 /* Sources */,
+				4B75C1E62F1A233500761A12 /* Frameworks */,
+				4B75C1E82F1A233500761A12 /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+				4B75C1EB2F1A233500761A12 /* PBXTargetDependency */,
+			);
+			fileSystemSynchronizedGroups = (
+				4B75C1E52F1A233500761A12 /* ComputerSolitaireTests */,
+			);
+			name = ComputerSolitaireTests;
+			packageProductDependencies = (
+			);
+			productName = ComputerSolitaireTests;
+			productReference = 4B75C1E42F1A233500761A12 /* ComputerSolitaireTests.xctest */;
+			productType = "com.apple.product-type.bundle.unit-test";
+		};
 /* End PBXNativeTarget section */
 
 /* Begin PBXProject section */
@@ -96,6 +144,10 @@
 					4B75C1D02F1A233400761A12 = {
 						CreatedOnToolsVersion = 26.2;
 					};
+					4B75C1E92F1A233500761A12 = {
+						CreatedOnToolsVersion = 26.2;
+						TestTargetID = 4B75C1D02F1A233400761A12;
+					};
 				};
 			};
 			buildConfigurationList = 4B75C1CC2F1A233400761A12 /* Build configuration list for PBXProject "ComputerSolitaire" */;
@@ -113,6 +165,7 @@
 			projectRoot = "";
 			targets = (
 				4B75C1D02F1A233400761A12 /* ComputerSolitaire */,
+				4B75C1E92F1A233500761A12 /* ComputerSolitaireTests */,
 			);
 		};
 /* End PBXProject section */
@@ -125,6 +178,13 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		4B75C1E82F1A233500761A12 /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXResourcesBuildPhase section */
 
 /* Begin PBXSourcesBuildPhase section */
@@ -135,8 +195,23 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		4B75C1E72F1A233500761A12 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXSourcesBuildPhase section */
 
+/* Begin PBXTargetDependency section */
+		4B75C1EB2F1A233500761A12 /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = 4B75C1D02F1A233400761A12 /* ComputerSolitaire */;
+			targetProxy = 4B75C1EA2F1A233500761A12 /* PBXContainerItemProxy */;
+		};
+/* End PBXTargetDependency section */
+
 /* Begin XCBuildConfiguration section */
 		4B75C1E02F1A233500761A12 /* Debug */ = {
 			isa = XCBuildConfiguration;
@@ -170,7 +245,7 @@
 				LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks";
 				"LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks";
 				MACOSX_DEPLOYMENT_TARGET = 26.2;
-				MARKETING_VERSION = 0.4.1;
+				MARKETING_VERSION = 0.5.0;
 				PRODUCT_BUNDLE_IDENTIFIER = crapshack.ComputerSolitaire;
 				PRODUCT_NAME = "Computer Solitaire";
 				REGISTER_APP_GROUPS = YES;
@@ -220,7 +295,7 @@
 				LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks";
 				"LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks";
 				MACOSX_DEPLOYMENT_TARGET = 26.2;
-				MARKETING_VERSION = 0.4.1;
+				MARKETING_VERSION = 0.5.0;
 				PRODUCT_BUNDLE_IDENTIFIER = crapshack.ComputerSolitaire;
 				PRODUCT_NAME = "Computer Solitaire";
 				REGISTER_APP_GROUPS = YES;
@@ -354,6 +429,42 @@
 			};
 			name = Release;
 		};
+		4B75C1ED2F1A233500761A12 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = T778QMSML9;
+				GENERATE_INFOPLIST_FILE = YES;
+				MACOSX_DEPLOYMENT_TARGET = 26.2;
+				PRODUCT_BUNDLE_IDENTIFIER = crapshack.ComputerSolitaireTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = auto;
+				SUPPORTED_PLATFORMS = macosx;
+				SWIFT_VERSION = 6.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Computer Solitaire.app/Contents/MacOS/Computer Solitaire";
+			};
+			name = Debug;
+		};
+		4B75C1EE2F1A233500761A12 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = T778QMSML9;
+				GENERATE_INFOPLIST_FILE = YES;
+				MACOSX_DEPLOYMENT_TARGET = 26.2;
+				PRODUCT_BUNDLE_IDENTIFIER = crapshack.ComputerSolitaireTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = auto;
+				SUPPORTED_PLATFORMS = macosx;
+				SWIFT_VERSION = 6.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Computer Solitaire.app/Contents/MacOS/Computer Solitaire";
+			};
+			name = Release;
+		};
 /* End XCBuildConfiguration section */
 
 /* Begin XCConfigurationList section */
@@ -375,6 +486,15 @@
 			defaultConfigurationIsVisible = 0;
 			defaultConfigurationName = Release;
 		};
+		4B75C1EC2F1A233500761A12 /* Build configuration list for PBXNativeTarget "ComputerSolitaireTests" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				4B75C1ED2F1A233500761A12 /* Debug */,
+				4B75C1EE2F1A233500761A12 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
 /* End XCConfigurationList section */
 	};
 	rootObject = 4B75C1C92F1A233400761A12 /* Project object */;