Sync packages from monorepo (ff638b7)

Author: github-actions[bot]

packages/cli/README.md

@@ -18,15 +18,15 @@ Save a CLI auth token. Generate one from studio.puzzmo.com.
 puzzmo login pzt-your-token-here
 ```
 
-### `puzzmo upload <slug> <dir>`
+### `puzzmo upload <dir>`
 
-Upload a game build directory to Puzzmo.
+Upload a game build directory to Puzzmo. The game slug is read from `puzzmo.json` in the build directory.
 
 ```bash
-puzzmo upload my-game dist/
+puzzmo upload dist/
 ```
 
-The command collects all files in the directory, computes a SHA from git (or file contents), and uploads them in batches.
+The command collects all files in the directory, validates the `puzzmo.json`, computes a SHA from git (or file contents), and uploads them in batches.
 
 ### `puzzmo game create [token]`
 

packages/cli/src/commands/upload.ts

@@ -45,7 +45,7 @@ const formatBytes = (bytes: number): string => {
 }
 
 /** Uploads game build artifacts to Puzzmo */
-export const upload = async (gameSlug: string, dir: string) => {
+export const upload = async (dir: string) => {
   const token = getToken()
   if (!token) {
     console.error("Not logged in. Run `puzzmo login <token>` or set PUZZMO_TOKEN.")
@@ -87,6 +87,7 @@ export const upload = async (gameSlug: string, dir: string) => {
     process.exit(1)
   }
   const puzzmoFile = validation.data
+  const gameSlug = puzzmoFile.game.slug
 
   // Determine SHA
   const sha = getGitSHA() || hashFiles(files)

packages/cli/src/index.ts

@@ -13,7 +13,7 @@ const printUsage = () => {
   puzzmo login <token>            Save a CLI auth token
   puzzmo game create [token]      Create a new Puzzmo game project
 
-  puzzmo upload <slug> <dir>      Upload game build from <dir>
+  puzzmo upload <dir>             Upload game build from <dir> (slug from puzzmo.json)
   puzzmo validate [dir]           Validate puzzmo.json in a directory (default: .)
   puzzmo migrate                  List and select migration skills from dev.puzzmo.com`)
 }
@@ -30,13 +30,12 @@ const run = async () => {
       break
     }
     case "upload": {
-      const gameSlug = args[0]
-      const dir = args[1]
-      if (!gameSlug || !dir) {
-        console.error("Usage: puzzmo upload <gameSlug> <dir>")
+      const dir = args[0]
+      if (!dir) {
+        console.error("Usage: puzzmo upload <dir>")
         process.exit(1)
       }
-      await upload(gameSlug, dir)
+      await upload(dir)
       break
     }
     case "game": {

packages/sdk/README.md

@@ -189,6 +189,39 @@ This and the editor bundle are separate JavaScript files from your main game.
 
 There are Vite plugins to make this easy, but otherwise, they should be files in your upload named `app-bundle.js` and `editor-bundle.js` with ESM exports which match the shapes of the TypeScript types.
 
+### Thumbnail JSX
+
+We have found over time that using JSX for thumbnails makes it a lot easier to ensure correct SVG output, but React/Preact are big runtimes, so we have a smaller JSX runtime built just for non-interactive SVGs based on [understated](https://github.com/callmecavs/understated).
+
+To use it, configure your file's JSX pragma to use `h` and `render` from `@puzzmo/sdk/svgJSX`:
+
+```tsx
+/** @jsxRuntime classic @jsx h */
+import { h, render } from "@puzzmo/sdk/svgJSX"
+
+// Needed for fragments
+const React = { Fragment: "g" }
+
+export function renderThumbnail(puzzleStr: string, inputStr?: string, config?: ThumbnailConfig): string {
+  const puzzle = JSON.parse(puzzleStr)
+  const size = 200
+
+  const svg = (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox={`0 0 ${size} ${size}`}>
+      <rect width={size} height={size} fill={config?.theme?.g_bg ?? "#1a1a2e"} />
+      <text x={size / 2} y={size / 2} textAnchor="middle" fill={config?.theme?.fg ?? "#fff"} fontSize="24">
+        {puzzle.title}
+      </text>
+    </svg>
+  )
+
+  const el = render(svg)
+  return el instanceof Element ? el.outerHTML : ""
+}
+```
+
+The `h` function is a JSX factory that creates virtual DOM nodes, and `render` converts them into real DOM elements. Since thumbnails can run server-side or in a DOM-shimmed environment, the result is serialized to an SVG string via `outerHTML`.
+
 ## Editor Integration
 
 For games that support puzzle editing in Puzzmo Workshop, you will need an Editor Bundle:

packages/sdk/package.json

@@ -32,6 +32,11 @@
       "import": "./dist/fonts.js",
       "require": "./dist/fonts.cjs"
     },
+    "./svgJSX": {
+      "types": "./dist/svgJSX.d.ts",
+      "import": "./dist/svgJSX.js",
+      "require": "./dist/svgJSX.cjs"
+    },
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js",
@@ -43,6 +48,7 @@
   ],
   "scripts": {
     "build": "vite build && tsgo --project tsconfig.build.json",
+    "test": "vitest run",
     "type-check": "tsgo --noEmit"
   },
   "keywords": [

packages/sdk/src/simulator/createSimulator.ts

@@ -1,35 +1,3 @@
-/**
- * Simulator - A development UI for testing games with the Puzzmo Proto SDK.
- *
- * This script simulates the Puzzmo host environment by:
- * - Listening for READY messages from the game
- * - Sending READY_DATA with puzzle data
- * - Providing UI controls for START_GAME, PAUSE_GAME, RESUME_GAME, RETRY_PUZZLE
- *
- * 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" })]
- * })
- * ```
- *
- * The plugin handles making sure it is removed on vite builds.
- *
- * Usage with manual imports:
- * ```html
- * <script type="module">
- *   import { createSimulator } from "@puzzmo/sdk/simulator"
- *   const fixtures = import.meta.glob("./fixtures/puzzles/**\/*.json", { eager: true })
- *   createSimulator({ fixtures })
- * </script>
- * ```
- * The fixtures folder structure should be: fixtures/puzzles/{category}/{puzzle}.json
- * This will show dropdowns in the Ctrl tab to select category and puzzle.
- */
-
 import type { BootstrapGameData, MessagesReceived } from "../types"
 import type { SimulatorConfig, SimulatorContext, SimulatorState, SimulatorView, TabName, FixtureImports } from "./types"
 import { simulatorStyles } from "./styles"
@@ -46,6 +14,7 @@ import {
   createThemeView,
   createAuthView,
   createFeaturesView,
+  createKeyboardView,
 } from "./views"
 
 // Re-export types for consumers
@@ -60,10 +29,40 @@ interface SimulatorInstance {
 let simulatorInstance: SimulatorInstance | null = null
 
 /**
- * Creates the Simulator UI and message handling.
- * If called multiple times, updates the existing instance with new settings (e.g., fixtures).
+ * Simulator - A development UI for testing games with the Puzzmo Proto SDK.
+ *
+ * This script simulates the Puzzmo host environment by:
+ * - Listening for READY messages from the game
+ * - Sending READY_DATA with puzzle data
+ * - Providing UI controls for START_GAME, PAUSE_GAME, RESUME_GAME, RETRY_PUZZLE
+ *
+ * Usage with Vite plugin (recommended):
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { puzzmoSimulator } from "@puzzmo/sdk/vite"
+ * export default defineConfig({
+ *   plugins: [puzzmoSimulator({})]
+ * })
+ * ```
+ *
+ * The plugin automatically reads the game slug from the nearest puzzmo.json.
+ *
+ * The plugin handles making sure it is removed on vite builds.
+ *
+ * Usage with manual imports:
+ * ```html
+ * <script type="module">
+ *   import { createSimulator } from "@puzzmo/sdk/simulator"
+ *   const fixtures = import.meta.glob("./fixtures/puzzles/**\/*.json", { eager: true })
+ *   createSimulator({ fixtures })
+ * </script>
+ * ```
+ * The fixtures folder structure should be: fixtures/puzzles/{category}/{puzzle}.json
+ * This will show dropdowns in the Ctrl tab to select category and puzzle.
  */
-function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
+
+export function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
   console.log("[Simulator] createSimulator called with config:", { slug: config.slug, hasFixtures: !!config.fixtures })
 
   // If instance already exists, update it with new config
@@ -94,6 +93,7 @@ function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
     createThemeView(),
     createAuthView(),
     createFeaturesView(),
+    createKeyboardView(),
   ] satisfies SimulatorView[]
 
   const validTabIds = views.map((v) => v.id)
@@ -582,5 +582,3 @@ function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
 
   return simulatorInstance
 }
-
-export { createSimulator }

packages/sdk/src/simulator/styles.ts

@@ -28,6 +28,7 @@ export const simulatorStyles = `
     border-radius: 4px;
     color: var(--sim-text);
     width: 420px;
+    max-width: calc(100vw - 8px);
     box-shadow: 4px 4px 0 rgba(0,0,0,0.5);
   }
   #simulator-panel.collapsed {
@@ -1071,4 +1072,78 @@ export const simulatorStyles = `
     color: var(--sim-text-dim);
     font-size: 9px;
   }
+  /* Keyboard view styles */
+  .keyboard-view-container {
+    padding: 4px;
+  }
+  .sim-kb-empty {
+    color: var(--sim-text-dim);
+    text-align: center;
+    padding: 16px 8px;
+    font-size: 10px;
+    line-height: 1.6;
+  }
+  .sim-kb-empty code {
+    background: var(--sim-bg);
+    padding: 1px 4px;
+    border-radius: 2px;
+    font-size: 10px;
+  }
+  .sim-kb {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  .sim-kb-row {
+    display: flex;
+    justify-content: center;
+    gap: 3px;
+  }
+  .sim-kb-key {
+    min-width: 28px;
+    height: 30px;
+    padding: 0 4px;
+    border: 1px solid var(--sim-border);
+    border-radius: 3px;
+    background: var(--sim-bg);
+    color: var(--sim-text);
+    font: inherit;
+    font-size: 11px;
+    text-transform: uppercase;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .sim-kb-key:hover {
+    background: var(--sim-bg-alt);
+    border-color: var(--sim-border-light);
+  }
+  .sim-kb-key:active {
+    background: var(--sim-accent);
+    color: var(--sim-panel);
+  }
+  .sim-kb-key.highlight {
+    background: var(--sim-bg-alt);
+    border-color: var(--sim-accent);
+    color: var(--sim-accent);
+    font-size: 9px;
+  }
+  .sim-kb-key.highlight:active {
+    background: var(--sim-accent);
+    color: var(--sim-panel);
+  }
+  .sim-kb-key.l {
+    min-width: 40px;
+  }
+  .sim-kb-key.xl {
+    min-width: 52px;
+  }
+  .sim-kb-key.grow {
+    flex: 1;
+  }
+  .sim-kb-key.disabled {
+    opacity: 0.3;
+    cursor: default;
+  }
 `