Sync packages from monorepo (40c7524)

Author: github-actions[bot]

packages/sdk/README.md

@@ -1,11 +1,30 @@
-# @puzzmo/sdk
+# Puzzmo Game Infra
 
-SDK for building games on the Puzzmo platform. Handles communication between your game and the Puzzmo host (puzzmo.com, embeds, native apps).
+Over the years we have a pretty refined route for making web games: prototype in HTML with no concern for code quality, share with people you like, then migrate it to a "real" codebase.
+
+LLMs have changed this, and we're finding that the 'prototype in HTML' phase is getting close enough to production quality that it does not always warrant a a multi-month conversion to React/TypeScript/Redux to ensure the codebase can live forever.
+
+So, after shipping two full games with this pipeline, we've knocked enough kinks out that it's ready for a more public space.
+
+So, how do you make a game? Well first, you need a game - we can't help there! However, once you do, then you can start migrating it to run on Puzzmo by: `yarn create puzzmo game`.
+
+## @puzzmo/sdk
+
+This repo is the SDK for building games on the Puzzmo platform. Handles communication between your game and Puzzmo.
+
+There are a few parts here!
+
+1. The SDK, e.g. the runtime API for launching a game, completing it and other essentials
+2. The simulator, which provides the same message sending infrastructure Puzzmo.com will send to your game
+3. App integration information, e.g. how to make custom thumbnails for your puzzles (and more)
+4. Vite plugins which can help you get up and running faster
 
 ## Install
 
 ```bash
 npm install @puzzmo/sdk
+
+yarn add @puzzmo/sdk
 ```
 
 ## Quick Start
@@ -43,33 +62,33 @@ Creates an SDK instance. Options:
 
 ### Lifecycle
 
-| Method                     | Description                                                                |
-| -------------------------- | -------------------------------------------------------------------------- |
-| `sdk.gameReady()`          | Async. Signals readiness, returns puzzle data and theme.                   |
-| `sdk.gameLoaded(state?)`   | Signals game UI is ready. Host will send `start`.                          |
-| `sdk.on(event, handler)`   | Listen for events: `start`, `pause`, `resume`, `retry`, `settingsUpdate`.  |
-| `sdk.off(event, handler)`  | Remove an event listener.                                                  |
+| Method                    | Description                                                               |
+| ------------------------- | ------------------------------------------------------------------------- |
+| `sdk.gameReady()`         | Async. Signals readiness, returns puzzle data and theme.                  |
+| `sdk.gameLoaded(state?)`  | Signals game UI is ready. Host will send `start`.                         |
+| `sdk.on(event, handler)`  | Listen for events: `start`, `pause`, `resume`, `retry`, `settingsUpdate`. |
+| `sdk.off(event, handler)` | Remove an event listener.                                                 |
 
 ### Game State
 
-| Method                                                      | Description                                                |
-| ----------------------------------------------------------- | ---------------------------------------------------------- |
-| `sdk.updateGameState(stateString, play?)`                   | Save current game state for persistence.                   |
-| `sdk.gameCompleted(play, config?)`                          | Signal game completion with metrics and deeds.             |
-| `sdk.showCompletionScreen(results, gameplay, showRetry?)`   | Show the Puzzmo completion UI.                             |
-| `sdk.hitCheckpoint(name, config, augConfig?)`               | Signal a gameplay milestone (for ads, leaderboards).       |
+| Method                                                    | Description                                          |
+| --------------------------------------------------------- | ---------------------------------------------------- |
+| `sdk.updateGameState(stateString, play?)`                 | Save current game state for persistence.             |
+| `sdk.gameCompleted(play, config?)`                        | Signal game completion with metrics and deeds.       |
+| `sdk.showCompletionScreen(results, gameplay, showRetry?)` | Show the Puzzmo completion UI.                       |
+| `sdk.hitCheckpoint(name, config, augConfig?)`             | Signal a gameplay milestone (for ads, leaderboards). |
 
 ### Timer
 
 The SDK manages a timer automatically (starts on `start`, pauses on `pause`, resets on `retry`).
 
 ```ts
-sdk.timer.timeMs()              // Elapsed time in ms
-sdk.timer.timeSecs()            // Elapsed time in seconds
-sdk.timer.display()             // ["1:23", "0:05"] (elapsed, penalty)
-sdk.timer.addPenalty(5000)      // Add 5s penalty
-sdk.timer.isPaused()            // Check if paused
-sdk.timer.isRunning()           // Check if running
+sdk.timer.timeMs() // Elapsed time in ms
+sdk.timer.timeSecs() // Elapsed time in seconds
+sdk.timer.display() // ["1:23", "0:05"] (elapsed, penalty)
+sdk.timer.addPenalty(5000) // Add 5s penalty
+sdk.timer.isPaused() // Check if paused
+sdk.timer.isRunning() // Check if running
 ```
 
 ## Theme
@@ -80,14 +99,14 @@ The `theme` object from `gameReady()` contains color tokens for the current Puzz
 const { theme } = await sdk.gameReady()
 
 // Key colors
-theme.g_bg       // Game background
-theme.fg         // Foreground text
-theme.key        // Primary accent
-theme.player     // Player color (blue)
-theme.alt1       // Accent green
-theme.alt2       // Accent yellow
-theme.alt3       // Accent purple
-theme.type       // "light" or "dark"
+theme.g_bg // Game background
+theme.fg // Foreground text
+theme.key // Primary accent
+theme.player // Player color (blue)
+theme.alt1 // Accent green
+theme.alt2 // Accent yellow
+theme.alt3 // Accent purple
+theme.type // "light" or "dark"
 ```
 
 See the `Theme` type export for the full list of tokens.
@@ -101,23 +120,42 @@ sdk.gameCompleted(metrics, {
   deeds: [
     { id: "moves", value: 42 },
     { id: "accuracy", value: 95 },
-    { id: "streak", value: 8 },
+    { id: "hit-streak", value: 8 },
   ],
 })
 ```
 
 The SDK automatically adds `points` and `time` deeds.
 
-## Workshop Types
+## App Integration
+
+For games to show a dynamic thumbnail, you will need an App Bundle
+
+```ts
+import type { EditorBundle, ValidationReport } from "@puzzmo/sdk"
+import { puzzleToSVG } from "./src/puzzleToSVG"
+
+export const AppBundle = {
+  renderThumbnail(puzzleString, boardState, config) {
+    return puzzleToSVG(puzzleString, boardState, config)
+  },
+} satisfies EditorBundle
+```
+
+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.
+
+## Editor Integration
 
-For games that support puzzle editing in Puzzmo Workshop:
+For games that support puzzle editing in Puzzmo Workshop, you will need an Editor Bundle:
 
 ```ts
-import type { WorkshopBundle, ValidationReport } from "@puzzmo/sdk"
+import type { EditorBundle, ValidationReport } from "@puzzmo/sdk"
 
 export const validator = {
-  validate(data: string): ValidationReport {
+  validate(data) {
     return { success: true, issues: [] }
   },
-}
+} satisfies EditorBundle
 ```

packages/sdk/src/workshop.ts packages/sdk/src/editor.tspackages/sdk/src/workshop.ts renamed to packages/sdk/src/editor.ts

@@ -19,14 +19,14 @@ export interface ValidationReport {
 export type ImportErrorType = "invalid_format" | "parsing_error" | "unknown"
 
 /** Custom error class for workshop import failures */
-export class WorkshopImportError extends Error {
+export class EditorImportError extends Error {
   constructor(
     public type: ImportErrorType,
     message: string,
     public originalError?: unknown,
   ) {
     super(message)
-    this.name = "WorkshopImportError"
+    this.name = "EditorImportError"
   }
 }
 
@@ -39,12 +39,26 @@ export interface ImportResult {
   editors?: string[]
 }
 
+/** Settings UI descriptor returned by an editor bundle */
+export interface EditorBundleSettings<TComponent = unknown> {
+  components: TComponent[]
+  defaults: Record<string, unknown>
+}
+
 /** Main interface for a Workshop bundle */
-export interface WorkshopBundle {
+export interface EditorBundle<TSettingsComponent = unknown> {
   validator: {
     validate(data: string): Promise<ValidationReport> | ValidationReport
   }
   importer?: {
     onImport(filename: string, contents: string | ArrayBuffer): Promise<ImportResult> | ImportResult
   }
+  /** Embed-level settings UI, populated from the bundle's declared settings */
+  settings?: EditorBundleSettings<TSettingsComponent>
+  /** Editor-level settings UI, populated from the bundle's declared editor settings */
+  editorSettings?: EditorBundleSettings<TSettingsComponent>
+  /** Custom puzzle editor, if provided by the bundle */
+  editor?: {
+    mount(...args: unknown[]): unknown
+  }
 }

packages/sdk/src/index.ts

@@ -1,5 +1,7 @@
 export { createPuzzmoSDK } from "./sdk"
+
 export type { SDK as PuzzmoSDK, PuzzmoSDKOptions, SDKEventMap, SDKEventType, SDKTimer } from "./sdk"
+
 export type {
   Theme,
   GamePlay,
@@ -11,6 +13,8 @@ export type {
   MessagesReceived,
   MessagesSentFromEmbed,
   ThumbnailConfig,
-  ThumbnailFunction,
 } from "./types"
-export * from "./workshop"
+
+export type { ValidationIssue, ValidationReport, ImportErrorType, ImportResult, EditorBundle } from "./editor"
+
+export { EditorImportError } from "./editor"

packages/sdk/src/sdk.ts

@@ -1,12 +1,4 @@
-import type {
-  MessagesSentFromEmbed,
-  MessagesReceived,
-  GamePlay,
-  AugmentationConfig,
-  CheckpointConfig,
-  Theme,
-  Deed,
-} from "./types"
+import type { MessagesSentFromEmbed, MessagesReceived, GamePlay, AugmentationConfig, CheckpointConfig, Theme, Deed } from "./types"
 
 export type SDK = ReturnType<typeof createPuzzmoSDK>
 
@@ -159,27 +151,22 @@ function createHostAPI() {
   const sendMessage = <T extends keyof SupportedOutgoingMessages>(type: T, json: SupportedOutgoingMessages[T]) => {
     const message = { type, json, _: "p", __: "mp", private: true }
 
-    if ("parent" in window && window.parent !== window)
-      window.parent.postMessage(message, "*")
+    if ("parent" in window && window.parent !== window) window.parent.postMessage(message, "*")
 
     window.postMessage(message, "*")
 
-    if ("webkit" in window && (window as any).webkit?.messageHandlers?.app)
-      (window as any).webkit.messageHandlers.app.postMessage(message)
+    if ("webkit" in window && (window as any).webkit?.messageHandlers?.app) (window as any).webkit.messageHandlers.app.postMessage(message)
 
-    if ("puzzmoMessageString" in window)
-      (window as any).puzzmoMessageString(JSON.stringify(message))
+    if ("puzzmoMessageString" in window) (window as any).puzzmoMessageString(JSON.stringify(message))
 
     if ("ReactNativeWebView" in window && (window as any).ReactNativeWebView?.postMessage)
       (window as any).ReactNativeWebView.postMessage(JSON.stringify(message))
 
-    if (type !== "TIMER_TICK" && type !== "TIMER_SYNC")
-      console.log("[Puzzmo SDK] sent:", type, json)
+    if (type !== "TIMER_TICK" && type !== "TIMER_SYNC") console.log("[Puzzmo SDK] sent:", type, json)
   }
 
   const onMessage = <T extends keyof SupportedIncomingMessages>(type: T, handler: MessageHandler<T>) => {
-    if (!messageHandlers.has(type))
-      messageHandlers.set(type, new Set())
+    if (!messageHandlers.has(type)) messageHandlers.set(type, new Set())
     messageHandlers.get(type)!.add(handler)
 
     return () => {
@@ -194,8 +181,7 @@ function createHostAPI() {
       const handlers = messageHandlers.get(msgType)
       if (handlers) {
         const msgData = event.data.data ?? event.data.json ?? {}
-        if (msgType !== "TIMER_TICK" && msgType !== "TIMER_SYNC")
-          console.log("[Puzzmo SDK] received:", msgType, msgData)
+        if (msgType !== "TIMER_TICK" && msgType !== "TIMER_SYNC") console.log("[Puzzmo SDK] received:", msgType, msgData)
         handlers.forEach((handler) => handler(msgData))
       }
     })
@@ -364,8 +350,7 @@ export const createPuzzmoSDK = (options: PuzzmoSDKOptions = {}) => {
     },
 
     on: <T extends SDKEventType>(event: T, listener: (data?: SDKEventMap[T]) => void): (() => void) => {
-      if (!eventListeners.has(event))
-        eventListeners.set(event, new Set())
+      if (!eventListeners.has(event)) eventListeners.set(event, new Set())
       eventListeners.get(event)!.add(listener)
       return () => {
         eventListeners.get(event)?.delete(listener)
@@ -386,13 +371,6 @@ export const createPuzzmoSDK = (options: PuzzmoSDKOptions = {}) => {
           boardState: inputString,
           elapsedTimeSecs: play?.elapsedTimeSecs ?? internalTimer.timeWithoutPenaltySecs(),
           additionalTimeAddedSecs: play?.additionalTimeAddedSecs ?? internalTimer.addedTimeSecs(),
-          hintsUsed: play?.hintsUsed,
-          resetsUsed: play?.resetsUsed,
-          metric1: 0,
-          metric2: 0,
-          metric3: 0,
-          metric4: 0,
-          metricStrings: [],
           collabUserReferences: [],
         },
       })

packages/sdk/src/simulator/createSimulator.ts

@@ -7,6 +7,7 @@
  * - 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"
@@ -15,6 +16,8 @@
  * })
  * ```
  *
+ * The plugin handles making sure it is removed on vite builds.
+ *
  * Usage with manual imports:
  * ```html
  * <script type="module">
@@ -414,11 +417,6 @@ function createSimulator(config: SimulatorConfig = {}): SimulatorInstance {
           elapsedTimeSecs: 0,
           hintsUsed: 0,
           id: `simulator-gameplay-${Date.now()}`,
-          metric1: 0,
-          metric2: 0,
-          metric3: 0,
-          metric4: 0,
-          metricStrings: [],
           ownerID: "simulator-owner",
           pointsAwarded: 0,
           resetsUsed: 0,

packages/sdk/src/simulator/views/DataView.ts

@@ -1,4 +1,4 @@
-import type { ThumbnailConfig, ThumbnailFunction } from "../../types"
+import type { AppBundle, ThumbnailConfig } from "../../types"
 import type { SimulatorContext, SimulatorView } from "../types"
 
 // Storage key for saved states (global across all puzzles)
@@ -7,11 +7,11 @@ const SAVED_STATES_KEY = "simulator-saved-states"
 /**
  * Find thumbnail function on globalThis (looks for functions ending in "Thumbnail")
  */
-function findThumbnailFn(): { name: string; fn: ThumbnailFunction } | null {
+function findThumbnailFn(): { name: string; fn: AppBundle["renderThumbnail"] } | null {
   const globalObj = globalThis as Record<string, unknown>
   for (const key of Object.keys(globalObj)) {
     if (key.endsWith("Thumbnail") && typeof globalObj[key] === "function") {
-      return { name: key, fn: globalObj[key] as ThumbnailFunction }
+      return { name: key, fn: globalObj[key] as AppBundle["renderThumbnail"] }
     }
   }
   return null

packages/sdk/src/simulator/views/ThumbView.ts

@@ -1,15 +1,15 @@
-import type { ThumbnailConfig, ThumbnailFunction } from "../../types"
+import type { AppBundle, ThumbnailConfig } from "../../types"
 import type { SimulatorContext, SimulatorView } from "../types"
 import { persistRenderContext, persistRenderHost } from "../state"
 
 /**
  * Find thumbnail function on globalThis (looks for functions ending in "Thumbnail")
  */
-function findThumbnailFn(): { name: string; fn: ThumbnailFunction } | null {
+function findThumbnailFn(): { name: string; fn: AppBundle["renderThumbnail"] } | null {
   const globalObj = globalThis as Record<string, unknown>
   for (const key of Object.keys(globalObj)) {
     if (key.endsWith("Thumbnail") && typeof globalObj[key] === "function") {
-      return { name: key, fn: globalObj[key] as ThumbnailFunction }
+      return { name: key, fn: globalObj[key] as AppBundle["renderThumbnail"] }
     }
   }
   return null