Sync packages from monorepo (d03ced6)

Author: github-actions[bot]

packages/sdk/src/simulator/createSimulator.ts

@@ -6,15 +6,16 @@
  * - Sending READY_DATA with puzzle data
  * - Providing UI controls for START_GAME, PAUSE_GAME, RESUME_GAME, RETRY_PUZZLE
  *
- * Usage in index.html:
- * ```html
- * <script type="module">
- *   import { createSimulator } from "@puzzmo/sdk/simulator"
- *   createSimulator({ puzzlePath: "./sample-puzzle.json", autoStart: true })
- * </script>
+ * Usage with Vite plugin (recommended):
+ * ```ts
+ * // vite.config.ts
+ * import { puzzmoSimulator } from "@puzzmo/sdk/vite"
+ * export default defineConfig({
+ *   plugins: [puzzmoSimulator({ slug: "my-game", fixturesGlob: "./fixtures/puzzles/**\/*.json" })]
+ * })
  * ```
  *
- * With fixtures (recommended for multiple puzzles):
+ * Usage with manual imports:
  * ```html
  * <script type="module">
  *   import { createSimulator } from "@puzzmo/sdk/simulator"
@@ -47,9 +48,6 @@ import {
 // Re-export types for consumers
 export type { SimulatorConfig, FixtureImports }
 
-// Default puzzle path
-const DEFAULT_PUZZLE_PATH = "./sample-puzzle.json"
-
 // Singleton instance state
 interface SimulatorInstance {
   updateFixtures: (fixtures: FixtureImports) => void
@@ -74,7 +72,6 @@ function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
     return simulatorInstance
   }
 
-  const puzzlePath = config.puzzlePath ?? DEFAULT_PUZZLE_PATH
   const autoStart = config.autoStart ?? true
 
   // Parse fixtures if provided
@@ -139,7 +136,10 @@ function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
         <div id="simulator-tabs">
           ${views
             .filter((v) => v.id !== "auth")
-            .map((v) => `<button class="simulator-tab" data-tab="${v.id}">${v.label}<span class="simulator-tab-badge" data-badge="${v.id}"></span></button>`)
+            .map(
+              (v) =>
+                `<button class="simulator-tab" data-tab="${v.id}">${v.label}<span class="simulator-tab-badge" data-badge="${v.id}"></span></button>`,
+            )
             .join("")}
         </div>
         <div id="simulator-content" class="hidden">
@@ -238,32 +238,37 @@ function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
     thumbView.updatePreview(context)
   }
 
-  // Load puzzle data
+  // Load puzzle data from fixtures
   const loadPuzzle = async (): Promise<any> => {
     if (state.puzzleData) return state.puzzleData
 
-    try {
-      const response = await fetch(puzzlePath)
-      if (!response.ok) {
-        throw new Error(`Failed to load puzzle from ${puzzlePath}`)
-      }
-      state.puzzleData = await response.json()
-      console.log("Simulator: Puzzle loaded", state.puzzleData)
-      state.originalPuzzle = JSON.stringify(state.puzzleData, null, 2)
+    if (!fixtures || fixtures.size === 0) {
+      throw new Error("No fixtures configured. Add puzzle JSON files to a fixtures directory and pass fixturesGlob to the simulator.")
+    }
 
-      // Update puzzle textarea if exists
-      const puzzleTextarea = getElement<HTMLTextAreaElement>("#simulator-puzzle")
-      if (puzzleTextarea) puzzleTextarea.value = state.originalPuzzle
+    // Pick the selected fixture, or the first one available
+    const category = state.selectedCategory ?? fixtureCategories[0]
+    const categoryMap = category ? fixtures.get(category) : undefined
+    if (!categoryMap || categoryMap.size === 0) {
+      throw new Error(`No puzzles found in fixture category "${category}"`)
+    }
 
-      // Refresh thumbnail if thumb tab is active
-      if (state.activeTab === "thumb") {
-        updateThumbnail()
-      }
-      return state.puzzleData
-    } catch (error) {
-      console.error("Simulator: Failed to load puzzle", error)
-      throw error
+    const puzzleName = state.selectedPuzzle ?? categoryMap.keys().next().value
+    const puzzleData = puzzleName ? categoryMap.get(puzzleName) : undefined
+    if (!puzzleData) {
+      throw new Error(`Puzzle "${puzzleName}" not found in category "${category}"`)
     }
+
+    state.puzzleData = puzzleData
+    console.log("Simulator: Puzzle loaded from fixtures", { category, puzzle: puzzleName })
+    state.originalPuzzle = JSON.stringify(state.puzzleData, null, 2)
+
+    const puzzleTextarea = getElement<HTMLTextAreaElement>("#simulator-puzzle")
+    if (puzzleTextarea) puzzleTextarea.value = state.originalPuzzle
+
+    if (state.activeTab === "thumb") updateThumbnail()
+
+    return state.puzzleData
   }
 
   // Wrapped sendToGame with logger

packages/sdk/src/simulator/standalone.ts

@@ -1,12 +1,12 @@
 /**
  * Standalone entry point for the simulator.
  *
- * Use as an IIFE script tag for non-Vite setups:
+ * Use as a script tag for non-Vite setups:
  * ```html
  * <script>
- *   window.SIMULATOR_CONFIG = { puzzlePath: "./sample-puzzle.json" }
+ *   window.SIMULATOR_CONFIG = { slug: "my-game" }
  * </script>
- * <script src="path/to/simulator/standalone.iife.js"></script>
+ * <script src="https://cdn.jsdelivr.net/npm/@puzzmo/sdk/dist/simulator/standalone.js"></script>
  * ```
  */
 import { createSimulator } from "./createSimulator"

packages/sdk/src/simulator/types.ts

@@ -4,8 +4,6 @@ import type { MessagesReceived, Theme, ThumbnailConfig } from "../types"
 export type FixtureImports = Record<string, { default?: any }>
 
 export interface SimulatorConfig {
-  /** Path to the puzzle JSON file (default: "./sample-puzzle.json") */
-  puzzlePath?: string
   /** Whether to auto-start the game after READY (default: true) */
   autoStart?: boolean
   /** Initial collapsed state (default: true) */

packages/sdk/src/vite.ts

@@ -1,8 +1,6 @@
 import type { Plugin } from "vite"
 
 export type PuzzmoSimulatorPluginOptions = {
-  /** Path to the puzzle JSON file (default: "./sample-puzzle.json") */
-  puzzlePath?: string
   /** Whether to auto-start the game after READY (default: true) */
   autoStart?: boolean
   /** Initial collapsed state (default: true) */

skills/introduce-puzzmo-sdk/SKILL.md

@@ -62,7 +62,21 @@ Add the `@puzzmo/sdk` package and wire up the game lifecycle.
 
 5. Wire up state saving - call `sdk.updateGameState(stateString)` whenever the game state changes so the host can save progress.
 
-6. Create a `sample-puzzle.json` file with test puzzle data that matches what the game expects.
+6. Create puzzle fixture files for local testing. Make a `fixtures/puzzles/` directory and add a few different puzzle JSON files that exercise different aspects of the game:
+
+   ```
+   fixtures/puzzles/
+     easy/
+       small-grid.json
+       basic.json
+     hard/
+       large-grid.json
+       tricky.json
+   ```
+
+   Each JSON file should contain puzzle data in the format the game expects. Try to create at least 2-3 puzzles with different characteristics (e.g. varying difficulty, size, or edge cases) so the game can be tested against realistic variety.
+
+   If the original game already has a few puzzles hardcoded, use those as a starting point for creating the fixture files. Then delete the buttons which may have been used to load them, since the simulator will handle loading puzzles from the fixtures.
 
 7. Set up the dev simulator for local testing. Add the Vite plugin to `vite.config.ts`:
 
@@ -74,21 +88,22 @@ Add the `@puzzmo/sdk` package and wire up the game lifecycle.
      plugins: [
        puzzmoSimulator({
          slug: "my-game",
-         puzzlePath: "./sample-puzzle.json",
+         fixturesGlob: "./fixtures/puzzles/**/*.json",
        }),
      ],
    })
    ```
 
    The plugin automatically:
    - Injects the simulator UI in dev mode only (tree-shaken from production builds)
+   - Loads fixtures from the glob pattern, organized by folder as categories
    - Handles OAuth callback routing for authenticated API features
 
    For non-Vite setups, load the SDK and simulator from jsDelivr:
 
    ```html
    <script>
-     window.SIMULATOR_CONFIG = { puzzlePath: "./sample-puzzle.json", slug: "my-game" }
+     window.SIMULATOR_CONFIG = { slug: "my-game" }
    </script>
    <script src="https://cdn.jsdelivr.net/npm/@puzzmo/sdk/dist/simulator/standalone.js"></script>
    ```
@@ -107,5 +122,5 @@ Add the `@puzzmo/sdk` package and wire up the game lifecycle.
 - Game initializes through SDK lifecycle (gameReady -> gameLoaded -> on start)
 - Game state is saved via `updateGameState` on each user action
 - Pause/resume/retry events are handled
-- A sample-puzzle.json exists for local testing
+- Fixture puzzles exist in `fixtures/puzzles/` with at least 2-3 varied puzzles
 - Simulator appears in dev mode but is not included in production builds