{"id":30297047,"url":"https://github.com/triformine/rubiks-cube-timer","last_synced_at":"2026-04-17T05:02:38.343Z","repository":{"id":307152253,"uuid":"1028274867","full_name":"TriForMine/rubiks-cube-timer","owner":"TriForMine","description":"A modern, feature-rich speedcubing timer with WCA-compliant scrambles, comprehensive statistics, and PWA support. Built with Next.js, React, and TypeScript.","archived":false,"fork":false,"pushed_at":"2025-08-30T14:32:42.000Z","size":1119,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T10:50:46.022Z","etag":null,"topics":["cube-timer","nextjs","react","rubiks-cube","speedcubing","timer","typescript"],"latest_commit_sha":null,"homepage":"https://rubikscubetimer.triformine.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TriForMine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T09:33:49.000Z","updated_at":"2025-08-04T13:55:43.000Z","dependencies_parsed_at":"2025-07-29T19:59:02.689Z","dependency_job_id":"d95ed66b-794e-417c-b143-e4953639d703","html_url":"https://github.com/TriForMine/rubiks-cube-timer","commit_stats":null,"previous_names":["triformine/rubiks-cube-timer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TriForMine/rubiks-cube-timer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TriForMine%2Frubiks-cube-timer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TriForMine%2Frubiks-cube-timer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TriForMine%2Frubiks-cube-timer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TriForMine%2Frubiks-cube-timer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TriForMine","download_url":"https://codeload.github.com/TriForMine/rubiks-cube-timer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TriForMine%2Frubiks-cube-timer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31915900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cube-timer","nextjs","react","rubiks-cube","speedcubing","timer","typescript"],"created_at":"2025-08-17T03:10:02.431Z","updated_at":"2026-04-17T05:02:38.308Z","avatar_url":"https://github.com/TriForMine.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rubik's Cube Timer\n\nA modern, feature-rich Rubik's cube timer built with Next.js, React, and TypeScript. Inspired by cstimer, this application provides a clean and professional interface for speedcubing practice and competition.\n\n## Features\n\n### 🎲 Core Functionality\n- **Accurate Timer**: High-precision timing with millisecond accuracy\n- **WCA Scramble Generator**: Official World Cube Association compliant 3x3x3 scrambles\n- **Spacebar Controls**: Standard speedcubing timer controls (hold to prepare, release to start)\n- **Time Tracking**: Comprehensive solve history with timestamps\n\n### 📊 Statistics \u0026 Analysis\n- **Comprehensive Stats**: Best, worst, mean, and current session statistics\n- **Standard Averages**: Ao5, Ao12, Ao50, and Ao100 calculations\n- **Visual Feedback**: Color-coded times based on performance\n- **Time Management**: Add penalties (+2, DNF) and delete individual solves\n\n### 🎨 User Experience\n- **Modern Dark Theme**: Easy on the eyes for long practice sessions\n- **Desktop Focused**: Optimized for desktop use with keyboard controls\n- **Visual State Indicators**: Clear feedback for timer states (ready, running, stopped)\n- **Keyboard Shortcuts**: Efficient navigation and control\n\n### 💾 Data Management\n- **Local Storage**: Automatic save/restore of times and settings\n- **Export/Import**: JSON-based backup and restore functionality\n- **Session Management**: Clear all times with confirmation\n\n## Getting Started\n\n### Prerequisites\n- [Bun](https://bun.sh/) (recommended) or Node.js 18+\n- Modern web browser\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/TriForMine/rubiks-cube-timer.git\n   cd rubiks-cube-timer\n   ```\n\n2. **Install dependencies**\n   ```bash\n   bun install\n   ```\n\n3. **Start the development server**\n   ```bash\n   bun run dev\n   ```\n\n4. **Open your browser**\n   Navigate to [http://localhost:3000](http://localhost:3000)\n\n### Build for Production\n\n```bash\n# Build the application\nbun run build\n\n# Start the production server\nbun run start\n```\n\n## Usage\n\n### Basic Timer Operation\n\n1. **Starting a Solve**\n   - Press and hold the SPACEBAR\n   - The timer will show \"HOLD\" state (red indicator)\n   - Continue holding until you see \"READY\" state (yellow indicator)\n   - Release SPACEBAR to start the timer\n\n2. **Stopping the Timer**\n   - Press SPACEBAR while the timer is running\n   - Your time will be automatically recorded\n   - A new scramble will be generated\n\n### Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `SPACE` | Start/Stop timer |\n| `N` | Generate new scramble |\n| `DELETE` | Delete last time |\n\n**Note**: The timer currently requires a physical keyboard and is optimized for desktop use. Mobile device support is planned for future releases.\n\n### Managing Times\n\n- **View Details**: Click on any time in the list to expand details\n- **Add Penalties**: Use the +2 or DNF buttons in expanded view\n- **Delete Times**: Click the trash icon to remove individual times\n- **Export Data**: Use Settings → Export Times to backup your data\n- **Import Data**: Use Settings → Import Times to restore from backup\n\n### Statistics Explained\n\n- **Best**: Your fastest solve time\n- **Mean**: Average of all solve times\n- **Ao5**: Average of 5 (best and worst times removed)\n- **Ao12**: Average of 12 (best and worst times removed)\n- **Ao50**: Average of 50 (best and worst times removed)\n- **Ao100**: Average of 100 (best and worst times removed)\n\n## Technology Stack\n\n- **Framework**: Next.js 15 with App Router\n- **Language**: TypeScript\n- **Styling**: Tailwind CSS v4\n- **UI Components**: shadcn/ui (Radix UI primitives)\n- **Icons**: Lucide React\n- **Package Manager**: Bun\n- **Runtime**: React 19\n- **Performance**: Rust WebAssembly (WASM) for cube simulation\n\n## Project Structure\n\n```\nsrc/\n├── app/\n│   ├── globals.css          # Global styles and Tailwind config\n│   ├── layout.tsx           # Root layout component\n│   └── page.tsx             # Main timer page\n├── components/\n│   ├── ui/                  # shadcn/ui components\n│   │   ├── button.tsx\n│   │   ├── card.tsx\n│   │   ├── dialog.tsx\n│   │   ├── dropdown-menu.tsx\n│   │   ├── tabs.tsx\n│   │   └── badge.tsx\n│   ├── Timer.tsx            # Main timer display\n│   ├── ScrambleDisplay.tsx  # Scramble generator and display\n│   ├── Cube3DViewer.tsx     # 3D cube visualization\n│   ├── TimesList.tsx        # Solve history list\n│   ├── Statistics.tsx       # Statistics dashboard\n│   └── Settings.tsx         # Application settings\n├── lib/\n│   ├── utils.ts             # Utility functions\n│   ├── cube-wasm.ts         # WASM module interface\n│   ├── cube-3d-renderer.ts  # Three.js 3D renderer\n│   └── scramble.ts          # Scramble generation logic\n└── cube-wasm/               # Rust WASM module\n    ├── src/                 # Rust source code\n    ├── pkg/                 # Compiled WASM files (committed)\n    ├── Cargo.toml           # Rust package config\n    └── README.md            # WASM module documentation\n```\n\n## High-Performance WASM Engine\n\nThis application features a custom Rust WebAssembly module for optimal performance:\n\n### Key Benefits\n- **Blazing Fast**: Cube simulation runs at native speeds\n- **Zero-Copy Memory**: Direct memory access between JS and WASM\n- **WCA Compliance**: Official scramble generation algorithms\n- **Type Safety**: Full TypeScript integration with WASM bindings\n\n### WASM Module Features\n- **Optimized Algorithms**: Efficient cube state representation and move execution\n- **Smart Scrambling**: Prevents invalid move sequences and ensures proper randomization\n- **Memory Efficient**: Minimal memory footprint with zero-copy data access\n- **Cross-Platform**: Compiled WASM files work across all browsers and platforms\n\n### Why WASM Files Are Committed\nThe compiled WASM files (`.wasm`, `.js`, `.d.ts`) are intentionally committed to the repository because:\n- **Deployment Compatibility**: Cloudflare Pages and similar platforms don't support Rust compilation\n- **Build Reliability**: Ensures consistent performance across all environments\n- **Zero Dependencies**: No need for Rust toolchain in production builds\n\nFor more details, see the [WASM module documentation](./cube-wasm/README.md).\n\n## Scramble Generation\n\nThe scramble generator creates WCA-compliant 3x3x3 cube scrambles:\n\n- **Standard Length**: 20 moves (configurable 15-30)\n- **Valid Moves**: R, L, U, D, F, B with modifiers (', 2)\n- **Smart Algorithm**: Prevents invalid sequences and ensures randomness\n- **Visual Display**: Moves grouped for easy reading\n- **3D Visualization**: Optional step-by-step 3D cube preview\n\n### Scramble Rules\n\n- No consecutive moves on the same face (e.g., R R')\n- No alternating opposite faces (e.g., R L R)\n- Proper randomization using cryptographically secure methods\n\n## Data Format\n\nTimes are stored in JSON format with the following structure:\n\n```json\n{\n  \"id\": \"1640995200000\",\n  \"time\": 15420,\n  \"scramble\": \"R U R' U' R' F R F' U2 R U' R'\",\n  \"date\": \"2023-12-31T23:59:59.999Z\",\n  \"penalty\": \"+2\"\n}\n```\n\n### Field Descriptions\n\n- `id`: Unique timestamp identifier\n- `time`: Solve time in milliseconds\n- `scramble`: WCA scramble string\n- `date`: ISO 8601 timestamp\n- `penalty`: Optional penalty (\"DNF\" or \"+2\")\n\n## Contributing\n\nWe welcome contributions from developers of all skill levels! Please see our [Contributing Guidelines](CONTRIBUTING.md) for detailed information on how to get started.\n\n### Quick Start for Contributors\n\n1. Fork the repository on GitHub\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes following our coding standards\n4. Test your changes thoroughly\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Development Guidelines\n\n- Follow TypeScript and React best practices\n- Use ESLint and Prettier for code formatting\n- Write meaningful commit messages\n- Test on multiple devices and browsers\n- Maintain accessibility standards\n- Read our [Code of Conduct](CODE_OF_CONDUCT.md)\n\nFor detailed contribution guidelines, development setup, and coding standards, please refer to [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Performance Optimizations\n\n- **Lazy Loading**: Components loaded on demand\n- **Memoization**: React.memo and useMemo for expensive calculations\n- **Local Storage**: Efficient data persistence\n- **Optimized Rendering**: Minimal re-renders during timer operation\n- **Tree Shaking**: Only necessary code included in build\n\n## Accessibility\n\n- **Keyboard Navigation**: Full keyboard support\n- **Screen Reader**: ARIA labels and semantic HTML\n- **Color Contrast**: WCAG 2.1 AA compliant\n- **Focus Indicators**: Clear focus states\n- **Reduced Motion**: Respects user preferences\n\n## Browser Support\n\n- Chrome 90+ (desktop)\n- Firefox 88+ (desktop)\n- Safari 14+ (desktop)\n- Edge 90+ (desktop)\n\n**Note**: Requires physical keyboard for timer controls. Mobile browsers are not currently supported.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n### Apache 2.0 License Summary\n\n- ✅ Commercial use allowed\n- ✅ Modification allowed  \n- ✅ Distribution allowed\n- ✅ Patent use allowed\n- ✅ Private use allowed\n- ℹ️ License and copyright notice required\n- ℹ️ State changes required\n\nFor the full license text, see [LICENSE](LICENSE).\n\n## Acknowledgments\n\n- Inspired by [cstimer](https://cstimer.net/) - the gold standard for online cube timers\n- [World Cube Association (WCA)](https://www.worldcubeassociation.org/) for scramble algorithms and regulations\n- The global speedcubing community for feedback and support\n- All contributors who help make this project better\n- Open source libraries and tools that make this project possible\n\n## Security\n\nIf you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) for responsible disclosure. Do not report security issues through public GitHub issues.\n\n## Roadmap\n\n### Planned Features\n\n#### High Priority\n- [ ] Mobile touch controls and responsive interface\n- [ ] Internationalization (i18n) and multiple language support\n- [ ] Multiple puzzle support (2x2, 4x4, etc.)\n- [ ] Advanced statistics and graphs\n- [ ] Competition mode with inspection time\n\n#### Medium Priority\n- [ ] Cloud synchronization\n- [ ] Custom themes\n- [ ] Session management\n- [ ] Training modes (F2L, OLL, PLL)\n- [ ] Sound effects and notifications\n\n#### Future Considerations\n- [ ] Mobile app (React Native)\n- [ ] Multiplayer racing\n- [ ] Advanced scramble algorithms\n- [ ] Competition timing features\n\n### Bug Reports\n\nIf you encounter any issues, please create an issue on GitHub with:\n\n- Steps to reproduce\n- Expected behavior\n- Actual behavior\n- Browser and version\n- Screenshots (if applicable)\n\n## FAQ\n\n**Q: How accurate is the timer?**\nA: The timer uses `performance.now()` for sub-millisecond accuracy and updates every 10ms during solving.\n\n**Q: Are the scrambles WCA official?**\nA: Yes, the scrambles follow WCA regulations for 3x3x3 cubes with proper move notation and sequence validation.\n\n**Q: Can I use this offline?**\nA: Yes, the app works offline after the initial load thanks to Next.js static optimization.\n\n**Q: Does this work on mobile devices?**\nA: Currently, the timer requires a physical keyboard for proper operation and is optimized for desktop use. Mobile support is planned for future releases.\n\n**Q: How do I backup my times?**\nA: Use the Export function in Settings to download a JSON file with all your data.\n\n**Q: Is my data private?**\nA: Yes, all data is stored locally in your browser. Nothing is sent to external servers. See our [Security Policy](SECURITY.md) for more details.\n\n**Q: Can I contribute to this project?**\nA: Absolutely! We welcome contributions. Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) to get started.\n\n---\n\n**Happy Cubing! 🎲**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriformine%2Frubiks-cube-timer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriformine%2Frubiks-cube-timer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriformine%2Frubiks-cube-timer/lists"}