@puzzmo/sdk 0.0.3 → 0.0.5

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

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

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":["import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\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":["createPuzzmoSDK","config"],"mappings":"gFAYO,SAASA,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAAA,CAC9C,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","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.d.ts

@@ -1,5 +1,6 @@
 import { GameConfig } from "./puzzmoSDK";
 export type * from "./puzzmoSDK";
+export * from "./workshop";
 /**
  * Creates a Puzzmo SDK instance
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,mBAAmB,aAAa,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU;;EAMjD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,mBAAmB,aAAa,CAAC;AAGjC,cAAc,YAAY,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU;;EAMjD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/index.iife.js

@@ -1,2 +1,2 @@
-var PuzzmoSDK=function(e){"use strict";function o(u){return{hello:()=>{console.log("Hello from Puzzmo SDK!",u)}}}return e.createPuzzmoSDK=o,Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),e}({});
+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/index.ts"],"sourcesContent":["import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\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":["createPuzzmoSDK","config"],"mappings":"uCAYO,SAASA,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAAA,CAC9C,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","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

@@ -1,11 +1,17 @@
-function e(o) {
+class s extends Error {
+  constructor(o, t, e) {
+    super(t), this.type = o, this.originalError = e, this.name = "WorkshopImportError";
+  }
+}
+function l(r) {
   return {
     hello: () => {
-      console.log("Hello from Puzzmo SDK!", o);
+      console.log("Hello from Puzzmo SDK!", r);
     }
   };
 }
 export {
-  e as createPuzzmoSDK
+  s as WorkshopImportError,
+  l as createPuzzmoSDK
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\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":["createPuzzmoSDK","config"],"mappings":"AAYO,SAASA,EAAgBC,GAAoB;AAClD,SAAO;AAAA,IACL,OAAO,MAAM;AACX,cAAQ,IAAI,0BAA0BA,CAAM;AAAA,IAAA;AAAA,EAC9C;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","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(e,o){typeof exports=="object"&&typeof module!="undefined"?o(exports):typeof define=="function"&&define.amd?define(["exports"],o):(e=typeof globalThis!="undefined"?globalThis:e||self,o(e.PuzzmoSDK={}))})(this,function(e){"use strict";function o(n){return{hello:()=>{console.log("Hello from Puzzmo SDK!",n)}}}e.createPuzzmoSDK=o,Object.defineProperty(e,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/index.ts"],"sourcesContent":["import { GameConfig } from \"./puzzmoSDK\";\n\n// Export the auto-generated public SDK types\nexport type * from \"./puzzmoSDK\";\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":["createPuzzmoSDK","config"],"mappings":"mPAYO,SAASA,EAAgBC,EAAoB,CAClD,MAAO,CACL,MAAO,IAAM,CACX,QAAQ,IAAI,yBAA0BA,CAAM,CAAA,CAC9C,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","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/workshop.d.ts

@@ -0,0 +1,155 @@
+import type { GameSettingsUIComponents } from "@puzzmo-com/shared/hostAPI";
+/**
+ * Severity level for validation issues.
+ *
+ * - `error`: Critical issue that prevents puzzle from being valid
+ * - `warning`: Issue that should be addressed but doesn't prevent usage
+ * - `info`: Informational message about the puzzle
+ */
+export type ValidationLevel = "error" | "warning" | "info";
+/** Represents a single validation issue found during puzzle validation. */
+export interface ValidationIssue {
+    /** Severity level of this validation issue */
+    level: ValidationLevel;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Line number in the puzzle data where the issue occurs (1-indexed, optional) */
+    line?: number;
+    /**
+     * Column position in the puzzle data where the issue occurs (1-indexed,
+     * optional)
+     */
+    col?: number;
+    /** Length of the problematic text segment for highlighting (optional) */
+    length?: number;
+}
+/**
+ * Complete validation report for a puzzle. Contains the overall validation
+ * status and any issues found.
+ */
+export interface ValidationReport {
+    /** Whether the puzzle passed validation without errors */
+    success: boolean;
+    /** Array of validation issues found (errors, warnings, and info messages) */
+    issues: ValidationIssue[];
+}
+/**
+ * Types of errors that can occur during puzzle import.
+ *
+ * - `invalid_format`: The file format is not supported or recognized
+ * - `parsing_error`: The file format is valid but parsing failed
+ * - `unknown`: An unexpected error occurred during import
+ */
+export type ImportErrorType = "invalid_format" | "parsing_error" | "unknown";
+/**
+ * Custom error class for workshop import failures. Thrown by the `onImport`
+ * function when a puzzle cannot be imported.
+ *
+ * @example
+ *
+ * ```typescript
+ * throw new WorkshopImportError(
+ *   "invalid_format",
+ *   "Unsupported file extension: .xyz",
+ * );
+ * ```
+ */
+export declare class WorkshopImportError extends Error {
+    /** The category of import error */
+    type: ImportErrorType;
+    /** Optional underlying error that caused the import to fail */
+    originalError?: unknown | undefined;
+    constructor(
+    /** The category of import error */
+    type: ImportErrorType, 
+    /** Human-readable error message */
+    message: string, 
+    /** Optional underlying error that caused the import to fail */
+    originalError?: unknown | undefined);
+}
+/**
+ * Result of a successful puzzle import operation. Contains the converted puzzle
+ * data and optional metadata.
+ */
+export interface ImportResult {
+    /**
+     * The converted puzzle data in the target format (e.g., XD format for
+     * crosswords)
+     */
+    data: string;
+    /** Optional validation warnings about the imported puzzle */
+    warnings?: ValidationIssue[];
+    /** Optional puzzle title extracted from the import file */
+    title?: string;
+    /** Optional list of puzzle authors */
+    authors?: string[];
+    /** Optional list of puzzle editors */
+    editors?: string[];
+}
+/**
+ * Main interface for a Workshop bundle. Workshop bundles are dynamically loaded
+ * modules that provide game-specific functionality for puzzle validation and
+ * import.
+ *
+ * @example
+ *
+ * ```typescript
+ * // In your workshop bundle (e.g., games/crossword/src/workshop/index.ts)
+ * export const validator = {
+ *   validate(data: string): ValidationReport {
+ *     // Custom validation logic
+ *     return { success: true, issues: [] };
+ *   },
+ * };
+ *
+ * export const importer = {
+ *   async onImport(
+ *     filename: string,
+ *     contents: string | ArrayBuffer,
+ *   ): Promise<ImportResult> {
+ *     // Custom import logic
+ *     return { data: convertedData };
+ *   },
+ * };
+ * ```
+ */
+export interface WorkshopBundle {
+    /** Required validator for puzzle data validation */
+    validator: {
+        /**
+         * Validates puzzle data and returns a report of issues.
+         *
+         * @param   data - The raw puzzle data string to validate
+         *
+         * @returns      Validation report with success status and any issues found
+         */
+        validate(data: string): Promise<ValidationReport> | ValidationReport;
+    };
+    /** Optional importer for converting external puzzle file formats */
+    importer?: {
+        /**
+         * Imports a puzzle file and converts it to the game's native format. Should
+         * throw `WorkshopImportError` for known failure cases.
+         *
+         * @param   filename                     - Name of the file being imported
+         * @param   contents                     - Raw file contents (string for
+         *   text files, ArrayBuffer for binary)
+         *
+         * @returns          Import result with converted data and optional metadata
+         *
+         * @throws  {WorkshopImportError}          For invalid or unsupported files
+         */
+        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>;
+    };
+}
+//# sourceMappingURL=workshop.d.ts.map

package/dist/workshop.d.ts.map

@@ -0,0 +1 @@
+{"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;CACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puzzmo/sdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Puzzmo runtime and API access for games",
   "type": "module",
   "main": "./dist/index.cjs",