{"_id":"@cardgamesplay/freecell","name":"@cardgamesplay/freecell","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cardgamesplay/freecell","version":"0.1.0","description":"Browser-based FreeCell Solitaire game built with TypeScript and vanilla DOM. Features drag-and-drop, keyboard navigation, card animations, sound effects, a music player, hint system, and i18n support for 16 languages. Play free at https://www.cardgamespla","license":"MIT","author":{"name":"Card Games Play"},"homepage":"https://www.cardgamesplay.com/","repository":{"type":"git","url":"git+https://github.com/bgbigbrother/freecell.git"},"bugs":{"url":"https://github.com/bgbigbrother/freecell/issues"},"funding":{"type":"individual","url":"https://www.cardgamesplay.com/"},"keywords":["freecell","solitaire","card-game","patience","browser-game","typescript","vanilla-js","drag-and-drop","keyboard-accessible","i18n","web-audio","free-online-game","canvas-game","html5-game"],"type":"module","main":"./src/index.ts","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./src/index.ts","default":"./dist/index.js","types":"./dist/index.d.ts"},"./game/*":{"import":"./dist/game/*.js","types":"./dist/game/*.d.ts"},"./ui/*":{"import":"./dist/ui/*.js","types":"./dist/ui/*.d.ts"},"./i18n":{"import":"./dist/i18n/index.js","types":"./dist/i18n/index.d.ts"},"./i18n/*":{"import":"./dist/i18n/*.js","types":"./dist/i18n/*.d.ts"}},"publishConfig":{"access":"public","main":"./dist/index.js","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./game/*":{"import":"./dist/game/*.js","types":"./dist/game/*.d.ts"},"./ui/*":{"import":"./dist/ui/*.js","types":"./dist/ui/*.d.ts"},"./i18n":{"import":"./dist/i18n/index.js","types":"./dist/i18n/index.d.ts"},"./i18n/*":{"import":"./dist/i18n/*.js","types":"./dist/i18n/*.d.ts"}}},"scripts":{"dev":"vite","build":"tsc -p tsconfig.build.json && vite build","prepublishOnly":"npm run build","test":"vitest --run"},"sideEffects":true,"engines":{"node":">=18"},"dependencies":{"@rse/soundlp":"^1.1.1"},"devDependencies":{"@vitest/ui":"^1.0.0","fast-check":"^3.0.0","happy-dom":"^20.8.9","typescript":"^5.0.0","vite":"^5.0.0","vitest":"^1.0.0"},"_id":"@cardgamesplay/freecell@0.1.0","gitHead":"3a02d8119fb4f2ffb76c64f804f24ace30106a70","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-M2dcDbsMrWbR2nPBaGyCBPmQvfVGTdinoqdUF7rgiYJhvfE50xKHYBoZRb8apk//UKK59sBfZu44N+RWtZhpZg==","shasum":"4a5491a8953515b253ec7052d2782a38ef92aa88","tarball":"https://registry.npmjs.org/@cardgamesplay/freecell/-/freecell-0.1.0.tgz","fileCount":98,"unpackedSize":30900780,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCVpun/0T7n0DwdWPOZiL6Q6IOpzwHlubLvviqbBhm3uQIhAPju0tnhRsQnFOZTTJtAzBmbukx4cbYrsHv3uNPEbQbz"}]},"_npmUser":{"name":"tedonash","email":"tedo.nash@gmail.com"},"directories":{},"maintainers":[{"name":"tedonash","email":"tedo.nash@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/freecell_0.1.0_1776881199959_0.34899499882357055"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T18:06:39.785Z","0.1.0":"2026-04-22T18:06:40.655Z","modified":"2026-04-22T18:06:41.024Z"},"maintainers":[{"name":"tedonash","email":"tedo.nash@gmail.com"}],"description":"Browser-based FreeCell Solitaire game built with TypeScript and vanilla DOM. Features drag-and-drop, keyboard navigation, card animations, sound effects, a music player, hint system, and i18n support for 16 languages. Play free at https://www.cardgamespla","homepage":"https://www.cardgamesplay.com/","keywords":["freecell","solitaire","card-game","patience","browser-game","typescript","vanilla-js","drag-and-drop","keyboard-accessible","i18n","web-audio","free-online-game","canvas-game","html5-game"],"repository":{"type":"git","url":"git+https://github.com/bgbigbrother/freecell.git"},"author":{"name":"Card Games Play"},"bugs":{"url":"https://github.com/bgbigbrother/freecell/issues"},"license":"MIT","readme":"# @cardgamesplay/freecell\n\nA browser-based FreeCell Solitaire game built with TypeScript, Vite, and vanilla DOM — no framework required. Features drag-and-drop, keyboard navigation, card animations, synthesised sound effects, a built-in music player, hint system, and full i18n support for 16 languages.\n\n**🎮 [Play the live demo at cardgamesplay.com](https://www.cardgamesplay.com/)**\n\n## Features\n\n- Classic FreeCell rules with 4 free cells, 4 foundations, and 8 tableau columns\n- Supermove support — move ordered sequences as a unit, limited by available free cells and empty columns\n- Drag-and-drop card movement with visual drop-target highlighting and stack ghost images\n- Full keyboard navigation — arrow keys to move between piles and zones, Space to select/place, Up/Down to resize selection, Escape to cancel\n- Hint engine that evaluates all legal moves and scores them with heuristics to suggest the best play\n- Animated card dealing and foundation fly-to transitions\n- Synthesised Web Audio API sound effects (card click, card drop, foundation chime) — no audio files needed\n- Built-in music player powered by `@rse/soundlp` with ambient tracks, play/pause, volume slider, and mute toggle\n- Undo support — every action is reversible all the way back to the opening deal\n- Auto-move safely sends eligible cards to foundations without blocking future tableau builds\n- Pause mode that hides all card faces and freezes the timer\n- Fullscreen support\n- Responsive layout that adapts to any viewport size, including mobile and orientation changes\n- Internationalisation (i18n) with 16 locales: English, Bulgarian, Spanish, French, German, Italian, Portuguese, Russian, Chinese, Japanese, Korean, Arabic (RTL), Hindi, Vietnamese, Polish, and Turkish\n- Language selector in the header and hamburger menu, with cross-tab sync via `localStorage`\n- Score tracking (+10 for each card moved to a foundation)\n- Win detection with a celebratory overlay showing final score, time, and move count\n- SVG card images via `cardsJS` with automatic CSS/Unicode fallback\n- Published as an ES module with typed exports for game engine, UI, and i18n\n\n## Project Structure\n\n```\n├── src/\n│   ├── index.ts              # App bootstrap — wires engine, renderer, drag-drop, keyboard, timer, UI\n│   ├── game/\n│   │   ├── types.ts           # Card, GameState, PileRef, Move, scoring constants\n│   │   ├── deck.ts            # createDeck() and Fisher-Yates shuffle\n│   │   ├── gameEngine.ts      # Core game logic — move, supermove, auto-move, undo\n│   │   ├── hintEngine.ts      # Heuristic hint system — evaluates and ranks all legal moves\n│   │   ├── scoring.ts         # Score delta helpers\n│   │   ├── winCondition.ts    # checkWin() — all four foundations complete\n│   │   ├── undoManager.ts     # Command-pattern undo stack\n│   │   └── deck.test.ts       # Unit + property-based tests for deck\n│   ├── ui/\n│   │   ├── renderer.ts        # DOM rendering — free cells, foundations, tableau, keyboard highlights\n│   │   ├── layout.ts          # Responsive layout calculator (card sizing, pile positions)\n│   │   ├── dragDrop.ts        # HTML5 drag-and-drop with validity checking and stack ghosts\n│   │   ├── keyboardController.ts # Full keyboard navigation across free cells, foundations, and tableau\n│   │   ├── cardAnimator.ts    # Deal and foundation-fly animations\n│   │   ├── audio.ts           # Synthesised sound effects (Web Audio API)\n│   │   ├── musicPlayer.ts     # Ambient music player with track selection and volume control\n│   │   └── langSelector.ts    # Language dropdown component\n│   └── i18n/\n│       ├── index.ts           # Locale registry, setLocale, applyLocale, cross-tab sync\n│       ├── init.ts            # Minimal bootstrap for static pages\n│       ├── en.ts              # English (canonical locale type)\n│       └── {bg,es,fr,de,it,pt,ru,zh,ja,ko,ar,hi,vi,pl,tr}.ts\n├── index.html                 # Standalone dev shell\n├── dev-entry.ts               # Dev entry point (imports shared styles + game)\n├── dev.css                    # Dev-mode style overrides\n├── package.json\n├── vite.config.ts             # Vite config (library build + dev server)\n├── vitest.config.ts           # Vitest config (happy-dom environment)\n├── tsconfig.json              # Dev/IDE TypeScript config\n└── tsconfig.build.json        # Build TypeScript config (emits declarations)\n```\n\n## Getting Started\n\n> Want to just play? Head over to **[cardgamesplay.com](https://www.cardgamesplay.com/)** — no install needed.\n\n### Prerequisites\n\n- Node.js ≥ 18\n- npm (or your preferred package manager)\n\n### Install\n\n```bash\nnpm install\n```\n\n### Development\n\n```bash\nnpm run dev\n```\n\nOpens a local Vite dev server with hot module replacement. The standalone dev shell at `index.html` includes a site header, language selector, and dev banner.\n\n### Build\n\n```bash\nnpm run build\n```\n\nCompiles TypeScript declarations via `tsc` and bundles the library as an ES module into `dist/`.\n\n### Test\n\n```bash\nnpm test\n```\n\nRuns all tests with Vitest in a `happy-dom` environment. The test suite includes:\n\n- Unit tests for deck creation, shuffle, and game engine moves\n- Property-based tests (via `fast-check`) covering shuffle permutation validity, card count preservation, and i18n persistence round-trips\n\n## Keyboard Shortcuts\n\n| Key | Action |\n|---|---|\n| ← → | Move cursor within the current row (top row or tableau) |\n| ↑ ↓ | Navigate between top row and tableau, or resize selection |\n| Space | Select card(s) or confirm a move |\n| Escape | Cancel current selection |\n| F2 | New game |\n| Ctrl+Z / Cmd+Z | Undo |\n\n## Game Rules\n\n1. All 52 cards are dealt face-up into 8 tableau columns — the first 4 columns receive 7 cards, the remaining 4 receive 6 cards. There is no stock or waste pile.\n2. There are 4 free cells that can each hold a single card temporarily.\n3. There are 4 foundation piles that build up by suit from Ace to King.\n4. Tableau columns build down in rank with alternating colours (red on black, black on red).\n5. Any card may be placed in an empty tableau column (not just Kings).\n6. Only one card at a time can be moved to or from a free cell.\n7. Supermove: ordered sequences of alternating-colour descending cards can be moved between tableau columns as a unit, provided there are enough empty free cells and empty tableau columns to theoretically perform the move one card at a time. The maximum moveable stack size is (empty free cells + 1) × 2^(empty tableau columns).\n8. Cards cannot be moved back from foundations.\n9. Complete all four foundations (Ace through King) to win.\n\n## Scoring\n\n| Action | Points |\n|---|---|\n| Any → Foundation | +10 |\n\nScore floor is 0 (never goes negative).\n\n## Internationalisation\n\nAll UI strings are driven by locale objects in `src/i18n/`. The `applyLocale()` function walks the DOM and updates elements tagged with `data-i18n`, `data-i18n-title`, `data-i18n-aria-label`, and other data attributes. Arabic is supported with automatic RTL layout.\n\nTo add a new language, duplicate `src/i18n/en.ts`, translate the values, and register the new locale in `src/i18n/index.ts`.\n\n## Tech Stack\n\n- TypeScript (strict mode, ES2020 target)\n- Vite (dev server + library build)\n- Vitest + happy-dom (testing)\n- fast-check (property-based testing)\n- `@rse/soundlp` (ambient music sprite)\n- `cardsJS` (SVG card images)\n- Web Audio API (synthesised sound effects)\n- Vanilla DOM (no UI framework)\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE.md).\n\n## Links\n\n- **[Play Online](https://www.cardgamesplay.com/)** — free, no sign-up, works on any device\n- [GitHub Repository](https://github.com/bgbigbrother/freecell)\n- [npm Package](https://www.npmjs.com/package/@cardgames/freecell)\n- [Report a Bug](https://github.com/bgbigbrother/freecell/issues)\n","readmeFilename":"README.md","_rev":"1-7c88bafa9c4bc507cd4bdd786adc8aae"}