Skip to content

markcoleman/CubeSolver

BranchesTags

Repository files navigation

🎲 CubeSolver - Next-Gen

iOS CI CodeQL codecov Swift Version Platform License GitHub release

A next-generation, modular iOS/iPadOS/macOS/watchOS application for solving Rubik's Cubes with camera scanning and a stunning glassmorphic interface.

CubeSolver

✨ Features

🎯 Core Features

  • Universal App: Runs seamlessly on iPhone, iPad, Mac, and Apple Watch
  • Modular Architecture: Clean Swift Package modules (CubeCore, CubeUI, CubeScanner, CubeAR)
  • Swift 6 Ready: Modern concurrency with async/await and Sendable conformance
  • Glassmorphism Design: Beautiful Mac-style UI with glass effects

📸 Camera Scanning (Core ML + Vision)

  • Live Camera View: Real-time cube scanning with AVFoundation
  • 3×3 Grid Overlay: Visual guide for accurate face scanning
  • Color Detection: Vision framework-powered sticker recognition
  • Confidence Scoring: Automatic quality assessment
  • Manual Correction: Fix low-confidence stickers with intuitive UI
  • 6-Face Scanning: Complete cube state capture

🧩 Solving & Validation

  • Enhanced Solver: Two-phase algorithm with async/await support
  • Physical Validation: Parity and orientation checks
  • Move Optimization: Efficient solution generation
  • Standard Notation: R, U', F2, etc.
  • Step-by-Step Solutions: Interactive playback with controls

📱 Multi-Device Support

  • Modern Navigation: SwiftUI NavigationStack
  • Home Dashboard: Recent solves and statistics
  • Solve History: Track all your solves with persistence
  • Privacy Controls: Opt-in analytics (disabled by default)
  • Settings: Comprehensive privacy and data management
  • watchOS Ready: Architecture supports Watch companion (coming soon)

🔒 Privacy & Security

  • Privacy First: All analytics opt-in only
  • Local Storage: UserDefaults-based persistence
  • Data Control: Clear history anytime
  • GDPR Compliant: Respect for user privacy

♿ Accessibility

  • VoiceOver: Full screen reader support
  • Accessibility Labels: All UI elements properly labeled
  • Dynamic Type: Text scaling support
  • High Contrast: Glassmorphic design works in all modes

🧪 Testing & Quality

  • 58+ Unit Tests: 100% pass rate
  • Modular Tests: Separate test suites for each module
  • CI/CD: GitHub Actions integration
  • Code Quality: SwiftLint enforcement

🚀 Getting Started

Requirements

  • Xcode: 26.0 or later (matches CI environment)
  • iOS/iPadOS: 26.0 or later
  • macOS: 26.0 or later
  • Swift: 6.2 or later
  • SwiftLint: For code quality checks (install via brew install swiftlint)

Quick Setup

  1. Clone the repository:
git clone https://github.com/markcoleman/CubeSolver.git
cd CubeSolver
  1. Resolve dependencies and build:
swift package resolve
swift build
  1. Run tests:
swift test --enable-code-coverage --parallel
  1. Open in Xcode:
open CubeSolver.xcodeproj

🛠️ Developer Environment Setup

Important: To ensure your local builds match CI builds, please follow the comprehensive setup guide:

📖 Local Development Environment Setup Guide

This guide covers:

  • Matching Xcode and Swift versions with CI
  • Resolving "works in CI, fails locally" issues
  • Pre-commit validation scripts
  • Build settings alignment
  • Troubleshooting common problems

Quick validation: Run the pre-commit check script to verify your environment matches CI:

./scripts/pre-commit-check.sh

🏗️ Architecture

CubeSolver follows a modular Swift Package architecture with clean separation of concerns:

📦 Swift Package Modules

CubeCore

Core business logic and models (platform-independent)

  • RubiksCube: 3D cube representation
  • CubeState: 54-sticker state management
  • EnhancedCubeSolver: Two-phase async solving algorithm
  • CubeValidator: Physical legality validation
  • Move/Turn/Amount: Standard notation types
  • Sendable conformance: Swift 6 concurrency support

CubeUI

SwiftUI views and view models

  • HomeView: Modern navigation hub
  • CubeViewModel: Main view model with async solving
  • CubeCamView: Camera-based auto-scan with video
  • ManualPhotoCaptureView: Manual single-shot camera mode
  • ManualInputView: Manual cube input
  • SolutionPlaybackView: Step-by-step playback
  • SolveHistoryManager: Persistence layer
  • PrivacySettings: Privacy controls
  • AnalyticsTracker: Opt-in analytics

CubeScanner

Vision and Core ML integration (iOS only)

  • CubeScanner: Camera-based cube detection
  • Sticker Detection: Vision framework integration
  • Color Classification: Core ML color recognition
  • Confidence Scoring: Quality assessment

CubeAR

ARKit and RealityKit integration (iOS only)

  • CubeARView: AR cube visualization
  • Virtual Cube: 3D animated cube model

🎯 Design Patterns

  • MVVM: Clear separation of UI and logic
  • Async/Await: Modern Swift concurrency
  • ObservableObject: Reactive state management
  • Modular Design: Clean dependencies
  • Protocol-Oriented: Flexible abstractions

🔄 Scan -> Solve Flow (New)

This repository now includes an additive scan pipeline and guided solve flow with DI-friendly boundaries.

Main Types

  • CubeCore:
    • FaceId, CubeFaceGrid, CubeStateAssembler
    • KociembaCodec, MoveNotationCodec
    • CubeStateValidator with structured ValidationError
    • CubeSolving protocol + KociembaCompatibleCubeSolver
  • CubeScanner:
    • CameraFrameSource, FaceQuadDetecting, StickerColorClassifying
    • DefaultFaceScanner, FaceWarpSampler, HSVStickerClassifier
    • VisionFaceQuadDetector and CameraSessionFrameSource adapters
    • SimulatedFaceScanner for tests and demos
  • CubeUI:
    • CubeScanSolveFlowViewModel
    • ScanWizardView, FaceConfirmView, CubeManualEditView, SolveStepsView
    • SolveModeView, SolveModeViewModel, SolveModeEngine

Solve Mode (Guided)

SolveModeView provides guided move-by-move solving with:

  • single-step controls (Back, Next, Play/Pause, speed, scrub slider)
  • deterministic state progression from initialState + moves
  • primary 3D visualization (CubeRenderer3DView) plus 2D fallback (CubeRenderer2DView)
  • human-readable move instructions and progress tracking

Orientation assumptions:

  • Scan Wizard uses fixed orientation from capture order: U, R, F, D, L, B.
  • In this flow, Front maps to scanned F, Up maps to scanned U.
  • When orientation is not guaranteed (for example manual input), enable requireOrientationConfirmation in SolveModeView to show an Orientation Lock confirmation step before playback.

Extending Renderers

Solve Mode rendering and animation are injected via protocols:

  • CubeRenderer: setState, highlight(move:), clearHighlight()
  • CubeMoveAnimator: move animation contract with completion callback

To add a renderer:

  1. Implement CubeRenderer for your view-backed renderer.
  2. Provide a CubeMoveAnimator implementation (or reuse TimedCubeMoveAnimator).
  3. Inject both into SolveModeViewModel for headless-testable behavior.

Running The Flow

Use dependency injection to choose live camera or simulated inputs.

import CubeCore
import CubeScanner
import CubeUI

let scanner = SimulatedFaceScanner(scriptedFaces: [
    .up: ScannedFaceData(id: .up, grid: CubeFaceGrid(repeating: .white), confidence: 1),
    .right: ScannedFaceData(id: .right, grid: CubeFaceGrid(repeating: .blue), confidence: 1),
    .front: ScannedFaceData(id: .front, grid: CubeFaceGrid(repeating: .red), confidence: 1),
    .down: ScannedFaceData(id: .down, grid: CubeFaceGrid(repeating: .yellow), confidence: 1),
    .left: ScannedFaceData(id: .left, grid: CubeFaceGrid(repeating: .green), confidence: 1),
    .back: ScannedFaceData(id: .back, grid: CubeFaceGrid(repeating: .orange), confidence: 1)
])

let vm = CubeScanSolveFlowViewModel(scanner: scanner)
let view = ScanWizardView(viewModel: vm)

Testing The Flow

Run all tests:

swift test --parallel

Run scanner-flow focused tests:

swift test --filter ScanSolvePipelineTests
swift test --filter ScanSolveFlowIntegrationTests

Run Solve Mode focused tests:

swift test --filter CubeMoveTests
swift test --filter CubeReducerTests
swift test --filter SolveModeEngineTests
swift test --filter MoveInstructionFormatterTests
swift test --filter SolveModeViewModelTests
swift test --filter SolveModeRenderingTests

Known Limitations

  • KociembaCompatibleCubeSolver currently delegates to the built-in search solver (clean swap point for a true two-phase backend).
  • DefaultFaceScanner depends on provided frame source quality; production camera UX tuning is still needed for low light and motion blur.
  • Perspective handling uses bilinear face interpolation; a full homography/OpenCV warp can further improve edge cases.

Next Improvements

  • Add adaptive per-device color calibration from center stickers over multiple frames.
  • Replace bilinear warping with true homography and temporal smoothing.
  • Plug in a dedicated Kociemba/two-phase backend behind CubeSolving.
  • Add UI test automation for scan wizard and manual edit conflict flows.

🎨 Glassmorphism Design

The app features a modern glassmorphic design inspired by macOS Big Sur and later:

  • Ultra-thin material backdrops
  • Subtle transparency and blur effects
  • Smooth animations and transitions
  • Responsive to system appearance (light/dark mode)

🧪 Testing

Unit Tests

Run the test suite:

swift test

Or in Xcode: Cmd + U

The project includes comprehensive unit tests for:

  • Data Structures: CubeState, Move notation, Face/Turn enums
  • Validation: Basic and physical legality checks
  • Cube Model: Face rotations and state management
  • Solver Algorithm: Two-phase solving with move generation
  • ViewModel Logic: State management and operations
  • Move Application: Scramble generation and application
  • Test Coverage: 56+ tests with 100% pass rate

UI Tests

UI tests with screenshot capture are available for:

  • Main interface validation
  • Scramble, solve, and reset workflows
  • Manual cube input interface
  • Accessibility features
  • Comprehensive screenshot gallery

Run UI tests in Xcode: Cmd + U (select CubeSolverUITests scheme)

Code Quality

The project uses SwiftLint for code quality enforcement:

swiftlint

Configuration is in .swiftlint.yml

📦 Project Structure

CubeSolver/
├── CubeSolver/
│   ├── Sources/
│   │   ├── CubeSolverApp.swift              # App entry point
│   │   ├── ContentView.swift                # Main UI
│   │   ├── CubeView.swift                   # Cube visualization
│   │   ├── CubeViewModel.swift              # ViewModel
│   │   ├── ManualInputView.swift            # Original manual input
│   │   ├── ValidatedManualInputView.swift   # Enhanced input with validation
│   │   ├── SolutionPlaybackView.swift       # Solution visualization
│   │   ├── RubiksCube.swift                 # 3D cube model
│   │   ├── CubeSolver.swift                 # Original solver
│   │   ├── EnhancedCubeSolver.swift         # Two-phase solver
│   │   ├── CubeDataStructures.swift         # Core data types
│   │   └── CubeValidation.swift             # Validation logic
│   ├── Tests/
│   │   ├── CubeSolverTests.swift            # Original tests
│   │   ├── CubeDataStructuresTests.swift    # Data structure tests
│   │   ├── CubeValidationTests.swift        # Validation tests
│   │   └── EnhancedCubeSolverTests.swift    # Solver tests
│   └── UITests/
│       └── CubeSolverUITests.swift          # UI tests
├── docs/                                     # Documentation
├── .github/
│   ├── workflows/                            # CI/CD
│   └── copilot-instructions.md              # Copilot config
├── .swiftlint.yml                           # Linting config
└── Package.swift                             # SPM manifest

🔧 Technologies

  • Language: Swift 6.2+
  • Framework: SwiftUI
  • Package Manager: Swift Package Manager
  • Testing: XCTest
  • CI/CD: GitHub Actions
  • Documentation: GitHub Pages

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

See CONTRIBUTING.md for detailed contribution guidelines.

🔄 CI/CD Workflows

Our GitHub Actions workflows are optimized to prevent duplicate runs and comments:

  • Automated PR checks with deduplication - no more duplicate comments
  • Smart workflow triggers to reduce unnecessary builds
  • Concurrency control to cancel outdated runs
  • Conditional screenshot capture - add screenshots label to trigger

See .github/WORKFLOWS.md for complete workflow documentation.

🤖 GitHub Copilot Agents

This repository includes specialized GitHub Copilot agents to assist with development:

  • SwiftUI Expert - UI components, platform-specific features, glassmorphic design
  • Algorithm Expert - Cube solving algorithms, data structures, performance
  • Accessibility Expert - VoiceOver, Dynamic Type, WCAG compliance
  • Testing Specialist - XCTest, code coverage, test quality
  • Documentation Expert - API docs, guides, technical writing
  • DevOps Expert - CI/CD, GitHub Actions, deployment

See .github/agents/README.md for details on using these agents.

📖 Documentation

Full documentation is available at https://markcoleman.github.io/CubeSolver

User Documentation

Developer Documentation

DevOps Documentation

🎯 Roadmap

  • Manual cube input for real-life cubes
  • Validated manual input with real-time feedback
  • Comprehensive accessibility support
  • UI testing with screenshot capture
  • Automated screenshot capture for App Store and documentation
  • SwiftLint code quality enforcement
  • Two-phase solving algorithm
  • Solution playback with interactive controls
  • Cube validation with physical legality checks
  • Standard move notation (R, U', F2, etc.)
  • 56+ comprehensive unit tests
  • Advanced solving algorithms (Kociemba's full implementation, CFOP)
  • Enhanced 3D cube visualization with SceneKit/RealityKit
  • Smooth solution animation playback
  • Statistics and solve time tracking
  • Camera-based cube scanning with Vision/CoreML (AR)
  • Multi-language support
  • Optimal move count optimization

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Inspired by the Rubik's Cube solving community
  • Built with ❤️ using SwiftUI
  • Glassmorphism design inspired by macOS

Made with ❤️ by the CubeSolver team

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages