@puzzmo/sdk 0.0.4 → 0.0.6

package/README.md

@@ -92,6 +92,52 @@ IIFE (Immediately Invoked Function Expression) is a more compact format ideal fo
 
 ## API Reference
 
+### Workshop Bundle
+
+The SDK exports the `WorkshopBundle` interface for games to provide Workshop-specific functionality like validation, import, and settings configuration.
+
+```typescript
+import type { WorkshopBundle } from "@puzzmo/sdk"
+
+const bundle: WorkshopBundle = {
+  validator: {
+    validate(data: string) {
+      // Validate puzzle data
+      return { success: true, issues: [] }
+    },
+  },
+  importer: {
+    onImport(filename: string, contents: string | ArrayBuffer) {
+      // Convert external formats to native format
+      return { data: convertedData }
+    },
+  },
+  settings: {
+    components: settingsUIComponents(), // GameSettingsUIComponents[]
+    defaults: defaultSettings(), // Record<string, unknown>
+  },
+}
+
+export default bundle
+```
+
+#### `WorkshopBundle.validator` (required)
+
+Validates puzzle data and returns a report of issues.
+
+#### `WorkshopBundle.importer` (optional)
+
+Imports external puzzle file formats and converts them to the game's native format.
+
+#### `WorkshopBundle.settings` (optional)
+
+Provides settings configuration for embed customization in Workshop:
+
+- `components`: Array of `GameSettingsUIComponents` defining the settings form UI
+- `defaults`: Object containing default values for all settings
+
+---
+
 ### `helloWorld(): string`
 
 Returns a hello world message from the Puzzmo SDK.

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"gFA2DO,MAAMA,UAA4B,KAAM,CAC7C,YAESC,EAEPC,EAEOC,EACP,CACA,MAAMD,CAAO,EANN,KAAA,KAAAD,EAIA,KAAA,cAAAE,EAGP,KAAK,KAAO,qBACd,CACF,CCxDO,SAASC,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAC9C,CAAA,CAEJ"}
+{"version":3,"file":"index.cjs","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["import type { GameSettingsUIComponents } from \"@puzzmo-com/shared/hostAPI\";\n\n/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n  /**\n   * Optional settings configuration for embed customization in Workshop. Allows\n   * Workshop to render a settings form for configuring embed overrides.\n   */\n  settings?: {\n    /** UI component definitions for rendering the settings form */\n    components: GameSettingsUIComponents[];\n    /** Default values for all settings */\n    defaults: Record<string, unknown>;\n  };\n\n  editor?: {\n    /** Called when first visiting a puzzle page. */\n    mount: (\n      element: HTMLElement,\n      config: {\n        puzzleString: string;\n        onChange: (puzzleString: string) => void;\n        theme: \"light\" | \"dark\";\n        width: number;\n        height: number;\n      },\n    ) => Promise<{\n      unmount: () => void;\n      /**\n       * Called whenever the puzzle string is updated in the editor from the\n       * outside, or when the theme or dimensions update. Workshop will rely on\n       * validator to reject / accept updates.\n       */\n      update: (config: {\n        puzzleString?: string;\n        theme?: \"light\" | \"dark\";\n        width?: number;\n        height?: number;\n      }) => void;\n    }>;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"gFA6DO,MAAMA,UAA4B,KAAM,CAC7C,YAESC,EAEPC,EAEOC,EACP,CACA,MAAMD,CAAO,EANN,KAAA,KAAAD,EAIA,KAAA,cAAAE,EAGP,KAAK,KAAO,qBACd,CACF,CC1DO,SAASC,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAC9C,CAAA,CAEJ"}

package/dist/index.iife.js

@@ -1,2 +1,2 @@
-var PuzzmoSDK=(function(r){"use strict";class t extends Error{constructor(n,u,l){super(u),this.type=n,this.originalError=l,this.name="WorkshopImportError"}}function e(o){return{hello:()=>{console.log("Hello from Puzzmo SDK!",o)}}}return r.WorkshopImportError=t,r.createPuzzmoSDK=e,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"}),r})({});
+var PuzzmoSDK=function(r){"use strict";class t extends Error{constructor(n,u,l){super(u),this.type=n,this.originalError=l,this.name="WorkshopImportError"}}function e(o){return{hello:()=>{console.log("Hello from Puzzmo SDK!",o)}}}return r.WorkshopImportError=t,r.createPuzzmoSDK=e,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"}),r}({});
 //# sourceMappingURL=index.iife.js.map

package/dist/index.iife.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.iife.js","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"wCA2DO,MAAMA,UAA4B,KAAM,CAC7C,YAESC,EAEPC,EAEOC,EACP,CACA,MAAMD,CAAO,EANN,KAAA,KAAAD,EAIA,KAAA,cAAAE,EAGP,KAAK,KAAO,qBACd,CACF,CCxDO,SAASC,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAC9C,CAAA,CAEJ"}
+{"version":3,"file":"index.iife.js","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["import type { GameSettingsUIComponents } from \"@puzzmo-com/shared/hostAPI\";\n\n/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n  /**\n   * Optional settings configuration for embed customization in Workshop. Allows\n   * Workshop to render a settings form for configuring embed overrides.\n   */\n  settings?: {\n    /** UI component definitions for rendering the settings form */\n    components: GameSettingsUIComponents[];\n    /** Default values for all settings */\n    defaults: Record<string, unknown>;\n  };\n\n  editor?: {\n    /** Called when first visiting a puzzle page. */\n    mount: (\n      element: HTMLElement,\n      config: {\n        puzzleString: string;\n        onChange: (puzzleString: string) => void;\n        theme: \"light\" | \"dark\";\n        width: number;\n        height: number;\n      },\n    ) => Promise<{\n      unmount: () => void;\n      /**\n       * Called whenever the puzzle string is updated in the editor from the\n       * outside, or when the theme or dimensions update. Workshop will rely on\n       * validator to reject / accept updates.\n       */\n      update: (config: {\n        puzzleString?: string;\n        theme?: \"light\" | \"dark\";\n        width?: number;\n        height?: number;\n      }) => void;\n    }>;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"uCA6DO,MAAMA,UAA4B,KAAM,CAC7C,YAESC,EAEPC,EAEOC,EACP,CACA,MAAMD,CAAO,EANN,KAAA,KAAAD,EAIA,KAAA,cAAAE,EAGP,KAAK,KAAO,qBACd,CACF,CC1DO,SAASC,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAC9C,CAAA,CAEJ"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"AA2DO,MAAMA,UAA4B,MAAM;AAAA,EAC7C,YAESC,GAEPC,GAEOC,GACP;AACA,UAAMD,CAAO,GANN,KAAA,OAAAD,GAIA,KAAA,gBAAAE,GAGP,KAAK,OAAO;AAAA,EACd;AACF;ACxDO,SAASC,EAAgBC,GAAoB;AAClD,SAAO;AAAA,IACL,OAAO,MAAM;AACX,cAAQ,IAAI,0BAA0BA,CAAM;AAAA,IAC9C;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"index.js","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["import type { GameSettingsUIComponents } from \"@puzzmo-com/shared/hostAPI\";\n\n/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n  /**\n   * Optional settings configuration for embed customization in Workshop. Allows\n   * Workshop to render a settings form for configuring embed overrides.\n   */\n  settings?: {\n    /** UI component definitions for rendering the settings form */\n    components: GameSettingsUIComponents[];\n    /** Default values for all settings */\n    defaults: Record<string, unknown>;\n  };\n\n  editor?: {\n    /** Called when first visiting a puzzle page. */\n    mount: (\n      element: HTMLElement,\n      config: {\n        puzzleString: string;\n        onChange: (puzzleString: string) => void;\n        theme: \"light\" | \"dark\";\n        width: number;\n        height: number;\n      },\n    ) => Promise<{\n      unmount: () => void;\n      /**\n       * Called whenever the puzzle string is updated in the editor from the\n       * outside, or when the theme or dimensions update. Workshop will rely on\n       * validator to reject / accept updates.\n       */\n      update: (config: {\n        puzzleString?: string;\n        theme?: \"light\" | \"dark\";\n        width?: number;\n        height?: number;\n      }) => void;\n    }>;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"AA6DO,MAAMA,UAA4B,MAAM;AAAA,EAC7C,YAESC,GAEPC,GAEOC,GACP;AACA,UAAMD,CAAO,GANN,KAAA,OAAAD,GAIA,KAAA,gBAAAE,GAGP,KAAK,OAAO;AAAA,EACd;AACF;AC1DO,SAASC,EAAgBC,GAAoB;AAClD,SAAO;AAAA,IACL,OAAO,MAAM;AACX,cAAQ,IAAI,0BAA0BA,CAAM;AAAA,IAC9C;AAAA,EAAA;AAEJ;"}

package/dist/index.umd.js

@@ -1,2 +1,2 @@
-(function(o,e){typeof exports=="object"&&typeof module!="undefined"?e(exports):typeof define=="function"&&define.amd?define(["exports"],e):(o=typeof globalThis!="undefined"?globalThis:o||self,e(o.PuzzmoSDK={}))})(this,(function(o){"use strict";class e extends Error{constructor(n,i,s){super(i),this.type=n,this.originalError=s,this.name="WorkshopImportError"}}function t(r){return{hello:()=>{console.log("Hello from Puzzmo SDK!",r)}}}o.WorkshopImportError=e,o.createPuzzmoSDK=t,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})}));
+(function(o,e){typeof exports=="object"&&typeof module!="undefined"?e(exports):typeof define=="function"&&define.amd?define(["exports"],e):(o=typeof globalThis!="undefined"?globalThis:o||self,e(o.PuzzmoSDK={}))})(this,function(o){"use strict";class e extends Error{constructor(n,i,s){super(i),this.type=n,this.originalError=s,this.name="WorkshopImportError"}}function t(r){return{hello:()=>{console.log("Hello from Puzzmo SDK!",r)}}}o.WorkshopImportError=e,o.createPuzzmoSDK=t,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})});
 //# sourceMappingURL=index.umd.js.map

package/dist/index.umd.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.umd.js","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"oPA2DO,MAAMA,UAA4B,KAAM,CAC7C,YAESC,EAEPC,EAEOC,EACP,CACA,MAAMD,CAAO,EANN,KAAA,KAAAD,EAIA,KAAA,cAAAE,EAGP,KAAK,KAAO,qBACd,CACF,CCxDO,SAASC,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAC9C,CAAA,CAEJ"}
+{"version":3,"file":"index.umd.js","sources":["../src/workshop.ts","../src/index.ts"],"sourcesContent":["import type { GameSettingsUIComponents } from \"@puzzmo-com/shared/hostAPI\";\n\n/**\n * Severity level for validation issues.\n *\n * - `error`: Critical issue that prevents puzzle from being valid\n * - `warning`: Issue that should be addressed but doesn't prevent usage\n * - `info`: Informational message about the puzzle\n */\nexport type ValidationLevel = \"error\" | \"warning\" | \"info\";\n\n/** Represents a single validation issue found during puzzle validation. */\nexport interface ValidationIssue {\n  /** Severity level of this validation issue */\n  level: ValidationLevel;\n  /** Human-readable description of the issue */\n  message: string;\n  /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */\n  line?: number;\n  /**\n   * Column position in the puzzle data where the issue occurs (1-indexed,\n   * optional)\n   */\n  col?: number;\n  /** Length of the problematic text segment for highlighting (optional) */\n  length?: number;\n}\n\n/**\n * Complete validation report for a puzzle. Contains the overall validation\n * status and any issues found.\n */\nexport interface ValidationReport {\n  /** Whether the puzzle passed validation without errors */\n  success: boolean;\n  /** Array of validation issues found (errors, warnings, and info messages) */\n  issues: ValidationIssue[];\n}\n\n/**\n * Types of errors that can occur during puzzle import.\n *\n * - `invalid_format`: The file format is not supported or recognized\n * - `parsing_error`: The file format is valid but parsing failed\n * - `unknown`: An unexpected error occurred during import\n */\nexport type ImportErrorType = \"invalid_format\" | \"parsing_error\" | \"unknown\";\n\n/**\n * Custom error class for workshop import failures. Thrown by the `onImport`\n * function when a puzzle cannot be imported.\n *\n * @example\n *\n * ```typescript\n * throw new WorkshopImportError(\n *   \"invalid_format\",\n *   \"Unsupported file extension: .xyz\",\n * );\n * ```\n */\nexport class WorkshopImportError extends Error {\n  constructor(\n    /** The category of import error */\n    public type: ImportErrorType,\n    /** Human-readable error message */\n    message: string,\n    /** Optional underlying error that caused the import to fail */\n    public originalError?: unknown,\n  ) {\n    super(message);\n    this.name = \"WorkshopImportError\";\n  }\n}\n\n/**\n * Result of a successful puzzle import operation. Contains the converted puzzle\n * data and optional metadata.\n */\nexport interface ImportResult {\n  /**\n   * The converted puzzle data in the target format (e.g., XD format for\n   * crosswords)\n   */\n  data: string;\n  /** Optional validation warnings about the imported puzzle */\n  warnings?: ValidationIssue[];\n  /** Optional puzzle title extracted from the import file */\n  title?: string;\n  /** Optional list of puzzle authors */\n  authors?: string[];\n  /** Optional list of puzzle editors */\n  editors?: string[];\n}\n\n/**\n * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded\n * modules that provide game-specific functionality for puzzle validation and\n * import.\n *\n * @example\n *\n * ```typescript\n * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)\n * export const validator = {\n *   validate(data: string): ValidationReport {\n *     // Custom validation logic\n *     return { success: true, issues: [] };\n *   },\n * };\n *\n * export const importer = {\n *   async onImport(\n *     filename: string,\n *     contents: string | ArrayBuffer,\n *   ): Promise<ImportResult> {\n *     // Custom import logic\n *     return { data: convertedData };\n *   },\n * };\n * ```\n */\nexport interface WorkshopBundle {\n  /** Required validator for puzzle data validation */\n  validator: {\n    /**\n     * Validates puzzle data and returns a report of issues.\n     *\n     * @param   data - The raw puzzle data string to validate\n     *\n     * @returns      Validation report with success status and any issues found\n     */\n    validate(data: string): Promise<ValidationReport> | ValidationReport;\n  };\n  /** Optional importer for converting external puzzle file formats */\n  importer?: {\n    /**\n     * Imports a puzzle file and converts it to the game's native format. Should\n     * throw `WorkshopImportError` for known failure cases.\n     *\n     * @param   filename                     - Name of the file being imported\n     * @param   contents                     - Raw file contents (string for\n     *   text files, ArrayBuffer for binary)\n     *\n     * @returns          Import result with converted data and optional metadata\n     *\n     * @throws  {WorkshopImportError}          For invalid or unsupported files\n     */\n    onImport(\n      filename: string,\n      contents: string | ArrayBuffer,\n    ): Promise<ImportResult> | ImportResult;\n  };\n  /**\n   * Optional settings configuration for embed customization in Workshop. Allows\n   * Workshop to render a settings form for configuring embed overrides.\n   */\n  settings?: {\n    /** UI component definitions for rendering the settings form */\n    components: GameSettingsUIComponents[];\n    /** Default values for all settings */\n    defaults: Record<string, unknown>;\n  };\n\n  editor?: {\n    /** Called when first visiting a puzzle page. */\n    mount: (\n      element: HTMLElement,\n      config: {\n        puzzleString: string;\n        onChange: (puzzleString: string) => void;\n        theme: \"light\" | \"dark\";\n        width: number;\n        height: number;\n      },\n    ) => Promise<{\n      unmount: () => void;\n      /**\n       * Called whenever the puzzle string is updated in the editor from the\n       * outside, or when the theme or dimensions update. Workshop will rely on\n       * validator to reject / accept updates.\n       */\n      update: (config: {\n        puzzleString?: string;\n        theme?: \"light\" | \"dark\";\n        width?: number;\n        height?: number;\n      }) => void;\n    }>;\n  };\n}\n","import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\n\n// Export workshop types\nexport * from \"./workshop\";\n\n/**\n * Creates a Puzzmo SDK instance\n *\n * @param   config - Configuration options\n *\n * @returns        A Puzzmo SDK instance\n */\nexport function createPuzzmoSDK(config: GameConfig) {\n  return {\n    hello: () => {\n      console.log(\"Hello from Puzzmo SDK!\", config);\n    },\n  };\n}\n\nexport type PuzzmoSDK = ReturnType<typeof createPuzzmoSDK>;\n"],"names":["WorkshopImportError","type","message","originalError","createPuzzmoSDK","config"],"mappings":"mPA6DO,MAAMA,UAA4B,KAAM,CAC7C,YAESC,EAEPC,EAEOC,EACP,CACA,MAAMD,CAAO,EANN,KAAA,KAAAD,EAIA,KAAA,cAAAE,EAGP,KAAK,KAAO,qBACd,CACF,CC1DO,SAASC,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAC9C,CAAA,CAEJ"}

package/dist/puzzmoSDK.d.ts

@@ -128,7 +128,7 @@ export type GameStateSubscriber = {
      */
     play: Partial<GamePlay>,
     /** These are legacy options, newer games will send an empty [] */
-    pipelineStats: any[],
+    pipelineStats: any[] | null,
     // For a small period of time, we sent leaderboards and deeds in this and the next arg positions, so you
     // should take into account that a game may send these from the past
     // Older game builds would not send this object

package/dist/workshop.d.ts

@@ -1,3 +1,4 @@
+import type { GameSettingsUIComponents } from "@puzzmo-com/shared/hostAPI";
 /**
  * Severity level for validation issues.
  *
@@ -140,5 +141,38 @@ export interface WorkshopBundle {
          */
         onImport(filename: string, contents: string | ArrayBuffer): Promise<ImportResult> | ImportResult;
     };
+    /**
+     * Optional settings configuration for embed customization in Workshop. Allows
+     * Workshop to render a settings form for configuring embed overrides.
+     */
+    settings?: {
+        /** UI component definitions for rendering the settings form */
+        components: GameSettingsUIComponents[];
+        /** Default values for all settings */
+        defaults: Record<string, unknown>;
+    };
+    editor?: {
+        /** Called when first visiting a puzzle page. */
+        mount: (element: HTMLElement, config: {
+            puzzleString: string;
+            onChange: (puzzleString: string) => void;
+            theme: "light" | "dark";
+            width: number;
+            height: number;
+        }) => Promise<{
+            unmount: () => void;
+            /**
+             * Called whenever the puzzle string is updated in the editor from the
+             * outside, or when the theme or dimensions update. Workshop will rely on
+             * validator to reject / accept updates.
+             */
+            update: (config: {
+                puzzleString?: string;
+                theme?: "light" | "dark";
+                width?: number;
+                height?: number;
+            }) => void;
+        }>;
+    };
 }
 //# sourceMappingURL=workshop.d.ts.map

package/dist/workshop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workshop.d.ts","sourceRoot":"","sources":["../src/workshop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,SAAS,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,mCAAmC;IAC5B,IAAI,EAAE,eAAe;IAG5B,+DAA+D;IACxD,aAAa,CAAC,EAAE,OAAO;;IAL9B,mCAAmC;IAC5B,IAAI,EAAE,eAAe;IAC5B,mCAAmC;IACnC,OAAO,EAAE,MAAM;IACf,+DAA+D;IACxD,aAAa,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,SAAS,EAAE;QACT;;;;;;WAMG;QACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;KACtE,CAAC;IACF,oEAAoE;IACpE,QAAQ,CAAC,EAAE;QACT;;;;;;;;;;;WAWG;QACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,WAAW,GAC7B,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;KACzC,CAAC;CACH"}
+{"version":3,"file":"workshop.d.ts","sourceRoot":"","sources":["../src/workshop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,SAAS,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,mCAAmC;IAC5B,IAAI,EAAE,eAAe;IAG5B,+DAA+D;IACxD,aAAa,CAAC,EAAE,OAAO;;IAL9B,mCAAmC;IAC5B,IAAI,EAAE,eAAe;IAC5B,mCAAmC;IACnC,OAAO,EAAE,MAAM;IACf,+DAA+D;IACxD,aAAa,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,SAAS,EAAE;QACT;;;;;;WAMG;QACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;KACtE,CAAC;IACF,oEAAoE;IACpE,QAAQ,CAAC,EAAE;QACT;;;;;;;;;;;WAWG;QACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,WAAW,GAC7B,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;KACzC,CAAC;IACF;;;OAGG;IACH,QAAQ,CAAC,EAAE;QACT,+DAA+D;QAC/D,UAAU,EAAE,wBAAwB,EAAE,CAAC;QACvC,sCAAsC;QACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC;IAEF,MAAM,CAAC,EAAE;QACP,gDAAgD;QAChD,KAAK,EAAE,CACL,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE;YACN,YAAY,EAAE,MAAM,CAAC;YACrB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;YACzC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;YACxB,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;SAChB,KACE,OAAO,CAAC;YACX,OAAO,EAAE,MAAM,IAAI,CAAC;YACpB;;;;eAIG;YACH,MAAM,EAAE,CAAC,MAAM,EAAE;gBACf,YAAY,CAAC,EAAE,MAAM,CAAC;gBACtB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;gBACzB,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,MAAM,CAAC,EAAE,MAAM,CAAC;aACjB,KAAK,IAAI,CAAC;SACZ,CAAC,CAAC;KACJ,CAAC;CACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puzzmo/sdk",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Puzzmo runtime and API access for games",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -42,7 +42,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@puzzmo-com/shared": "^0.0.13358",
+    "@puzzmo-com/shared": "^0.0.14332",
     "prettier": "^3.6.2",
     "prettier-plugin-jsdoc": "^1.5.0",
     "tsx": "catalog:",