Merge branch 'main' into feat-port-war-card-game

Author: steam-bell-92

README.md

@@ -240,7 +240,7 @@ deactivate
 
 ## 🌐 Web App Catalog
 
-The browser app currently exposes 38 projects:
+The browser app currently exposes 39 projects:
 
 ### Games
 
@@ -263,6 +263,7 @@ The browser app currently exposes 38 projects:
 - Word Scramble
 - Spot the Difference
 - War Card Game
+- Number Sliding Puzzle
 
 ### Math
 
@@ -294,7 +295,6 @@ The browser app currently exposes 38 projects:
 
 These standalone Python project files do not have a browser counterpart yet and are good future-port candidates:
 
-- [games/Number-Sliding-Puzzle/Number-Sliding-Puzzle.py](games/Number-Sliding-Puzzle/Number-Sliding-Puzzle.py)
 - [games/Reverse-Hangman-Game/Reverse-Hangman-Game.py](games/Reverse-Hangman-Game/Reverse-Hangman-Game.py)
 - [math/Happy-Number/Happy-Number.py](math/Happy-Number/Happy-Number.py)
 - [math/Matrix-Calculator/Matrix-Calculator.py](math/Matrix-Calculator/Matrix-Calculator.py)

games/Number-Sliding-Puzzle/Number-Sliding-Puzzle.py

@@ -8,14 +8,37 @@
 from utils.validation import get_int, get_yes_no
 
 
+def is_solvable(numbers):
+    """
+    Determines if the 8-puzzle board configuration is solvable.
+    An 8-puzzle (3x3 grid) is solvable if the number of inversions is even.
+    The blank tile (0) is ignored when counting inversions. 
+    """
+    # Filter out the blank tile(0)
+
+    tiles = [n for n in numbers if n != 0]
+    inversions = 0
+    for i in range(len(tiles)):
+        for j in range(i + 1, len(tiles)):
+            if tiles[i] > tiles[j]:
+                inversions += 1
+
+    # return True if inversions count is even, False otherwise
+
+    return inversions % 2 == 0
+
+
 def main():
     print("🧩 Emoji Sliding Puzzle Game 🧩")
 
     while True:
         print("Arrange the numbers in correct order!\n")
 
         numbers = [1, 2, 3, 4, 5, 6, 7, 8, 0]
-        random.shuffle(numbers)
+        while True:
+            random.shuffle(numbers)
+            if is_solvable(numbers) and numbers != [1, 2, 3, 4, 5, 6, 7, 8, 0]:
+                break
 
         puzzle = [
             numbers[0:3],

web-app/assets/banners/number-sliding-puzzle.webp

@@ -329,6 +329,25 @@
       <section class="projects-section" aria-label="Game Projects">
         <div class="container">
           <div class="projects-grid" id="projectsGrid">
+            <div
+              class="project-card"
+              data-category="games"
+              data-project="number-sliding-puzzle"
+            >
+              <img
+                class="card-banner"
+                src="assets/banners/number-sliding-puzzle.webp"
+                alt="Number Sliding Puzzle"
+                loading="lazy"
+              / loading="lazy">
+              <div class="card-actions">
+                <button class="btn-play" aria-label="Play Number Sliding Puzzle">Try It</button>
+              </div>
+
+              <h3>Number Sliding Puzzle</h3>
+              <p>Arrange numbers in ascending order by sliding them!</p>
+            </div>
+
             <div
               class="project-card"
               data-category="games"
@@ -712,6 +731,7 @@ <h3>Word Scramble</h3>
     <script defer src="js/projects/word-scramble.js"></script>
     <script defer src="js/projects/snake.js"></script>
     <script defer src="js/projects/spot-the-difference.js"></script>
+    <script defer src="js/projects/number-sliding-puzzle.js"></script>
     <script defer src="js/projects.js"></script>
     <script defer src="https://unpkg.com/lucide@latest/dist/umd/lucide.js"></script>
     <script defer type="module" src="js/main.js"></script>

web-app/games.html

@@ -100,6 +100,18 @@ def generate_banner(name, category, filename):
             y = 120 + (i // 2) * 120
             v_draw.rounded_rectangle([x, y, x + 140, y + 90], radius=12, fill=(255,255,255,8), outline=color_accent, width=2)
             v_draw.text((x + 70, y + 45), val, fill=color_accent, anchor="mm")
+    elif "sliding" in n_lower or "puzzle" in n_lower:
+        # Draw a 3x3 grid with sliding numbers
+        for i in range(9):
+            if i == 8:  # Empty space
+                continue
+            r_idx = i // 3
+            c_idx = i % 3
+            x = 240 + c_idx * 110
+            y = 120 + r_idx * 75
+            val = str(i + 1)
+            v_draw.rounded_rectangle([x, y, x + 90, y + 60], radius=10, fill=(255,255,255,12), outline=color_accent, width=2)
+            v_draw.text((x + 45, y + 30), val, fill=color_accent, anchor="mm")
     elif "fibonacci" in n_lower:
         # Draw golden spiral
         cx, cy = 400, 225
@@ -534,6 +546,7 @@ def draw_o(ox, oy):
     ("Progress Tracker", "utilities", "progress-tracker.webp"),
     ("Reverse Hangman", "games", "reverse-hangman.webp"),
     ("Chess Game", "games", "chess.webp"),
+    ("Number Sliding Puzzle", "games", "number-sliding-puzzle.webp"),
 
     # MATH
     ("AP/GP/AGP/HP Recognizer", "math", "progression-recognizer.webp"),

web-app/generate_banners.py

@@ -873,6 +873,7 @@ <h3>Legal</h3>
     <script defer type="module" src="js/main.js"></script>
     <script defer src="js/hero-canvas.js"></script>
     <script defer src="js/projects/war-card-game.js"></script>
+    <script defer src="js/projects/number-sliding-puzzle.js"></script>
     <script>
       lucide.createIcons();
     </script>
@@ -886,6 +887,13 @@ <h3>Legal</h3>
         // ALL projects from your js/projects/ folder
         const projectsData = [
           // GAMES (20+)
+          {
+            project: "number-sliding-puzzle",
+            title: "Number Sliding Puzzle",
+            category: "games",
+            desc: "Arrange tiles in order by sliding them into empty space",
+            tags: "game,puzzle,sliding,numbers",
+          },
           {
             project: "2048-game",
             title: "2048 Game",

web-app/index.html

@@ -1604,6 +1604,13 @@ const projectInstructions = {
       "The player with the higher card rank wins the round and gets a point.",
       "Ace is the highest, 2 is the lowest.",
       "Play continues until all cards are drawn. The player with the most points wins!"
+  "number-sliding-puzzle": {
+    title: "🧩 How to Play Number Sliding Puzzle",
+    steps: [
+      "Use arrow keys (← ↑ → ↓) or click/tap on tiles next to the empty space to slide them.",
+      "Arrange the numbers in ascending order from 1 to 8, with the blank space at the bottom right.",
+      "A moves counter keeps track of your steps.",
+      "Click the Reset button to restart the game."
     ]
   },
   "2048-game": {
@@ -1740,6 +1747,16 @@ const projectInstructions = {
       "Beat the dealer to win"
     ]
   },
+  "reverse-hangman": {
+  title: "🤖 How to Play Reverse Hangman",
+  steps: [
+    "Think of a secret word from the dictionary (40+ words available)",
+    "The AI tries to guess your word using letter frequency analysis",
+    "Tell the AI if its guess is correct or not",
+    "AI gets 8 attempts max — can you beat the computer?",
+    "Watch the hangman visual feedback as AI guesses"
+  ]
+},
 
   // MATH
   "calculator": {
@@ -1843,6 +1860,16 @@ const projectInstructions = {
       "Click Recognize to identify the sequence type"
     ]
   },
+  "matrix-calculator": {
+    title: "🧮 How to Use Matrix Calculator",
+    steps: [
+        "Select matrix dimensions (rows × columns)",
+        "Enter values into each cell",
+        "Choose operation: Addition, Subtraction, Multiplication, Transpose, Determinant, Rank, or Inverse",
+        "Click Calculate to see the result",
+        "Determinant & Inverse work only for square matrices"
+    ]
+  },
 
   // UTILITIES
   "color-palette": {
@@ -1920,7 +1947,17 @@ const projectInstructions = {
       "Mark projects as complete",
       "See your progress over time"
     ]
-  }
+  },
+  "unit-converter": {
+    title: "📏 How to Use Unit Converter",
+    steps: [
+        "Select conversion category (Length, Mass, Temperature, etc.)",
+        "Choose input and output units",
+        "Enter the value to convert",
+        "Result appears instantly",
+        "Supports multiple unit types"
+  ]
+}
 };
 
 function getProjectInstructions(projectName) {
@@ -3140,6 +3177,7 @@ function initializeProject(projectName) {
     "resume-analyzer": "initResumeAnalyzer",
     "caesar-cipher": "initCaesarCipher",
     "war-card-game": "initWarCardGame"
+    "number-sliding-puzzle": "initNumberSlidingPuzzle"
   };
 
   const initializerName = initializers[projectName];