@playcademy/sdk 0.0.1-beta.19 → 0.0.1-beta.20

package/dist/messaging.d.ts

@@ -198,13 +198,12 @@ declare class PlaycademyMessaging {
      * This is the main public API for sending messages in the Playcademy system.
      *
      * **How It Works**:
-     * 1. If options.target is provided, always use postMessage to that target
-     * 2. Otherwise, analyzes the message type and current runtime context
-     * 3. Determines if we're in an iframe and if this message should use postMessage
-     * 4. Routes to the appropriate transport method (postMessage or CustomEvent)
+     * 1. Analyzes the message type and current runtime context
+     * 2. Determines if we're in an iframe and if this message should use postMessage
+     * 3. Routes to the appropriate transport method (postMessage or CustomEvent)
      *
      * **Transport Selection Logic**:
-     * - **postMessage**: Used when target is specified OR when game is in iframe sending to parent
+     * - **postMessage**: Used when game is in iframe and sending to parent, OR when target window is specified
      * - **CustomEvent**: Used for local/same-context communication
      *
      * **Type Safety**:
@@ -214,21 +213,24 @@ declare class PlaycademyMessaging {
      * @template K - The message event type (ensures type safety)
      * @param type - The message event type to send
      * @param payload - The data to send with the message (type-checked)
-     * @param options - Optional configuration for target window and origin
+     * @param options - Optional configuration for message sending
      *
      * @example
      * ```typescript
-     * // Send game ready signal (auto-detected transport)
+     * // Send game ready signal (no payload)
      * messaging.send(MessageEvents.READY, undefined)
      *
-     * // Send to specific iframe (parent → game)
+     * // Send telemetry data (typed payload)
+     * messaging.send(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     *
+     * // Send to specific iframe window (parent to iframe communication)
      * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId }, {
      *   target: iframe.contentWindow,
-     *   origin: 'https://game.example.com'
+     *   origin: '*'
      * })
      *
-     * // Send telemetry data (auto-detected transport)
-     * messaging.send(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     * // TypeScript will error if payload type is wrong
+     * messaging.send(MessageEvents.INIT, "wrong type") // ❌ Error
      * ```
      */
     send<K extends MessageEvents>(type: K, payload: MessageEventMap[K], options?: {
@@ -331,17 +333,16 @@ declare class PlaycademyMessaging {
      * **Message Direction Analysis**:
      * Different message types flow in different directions:
      * - **Game → Parent**: READY, EXIT, TELEMETRY (use postMessage when in iframe)
-     * - **Parent → Game**: INIT, TOKEN_REFRESH, PAUSE, etc. (use CustomEvent in local dev)
+     * - **Parent → Game**: INIT, TOKEN_REFRESH, PAUSE, etc. (use CustomEvent in local dev, or postMessage with target)
      *
      * **Cross-Context Communication**:
-     * This messaging system now handles ALL communication patterns:
-     * - Game → Parent: Automatic detection and postMessage
-     * - Parent → Game: Use options.target to specify the iframe window
-     * - Local development: Automatic CustomEvent fallback
+     * The messaging system supports cross-context targeting through the optional `target` parameter.
+     * When a target window is specified, postMessage is used regardless of the current context.
+     * This enables parent-to-iframe communication through the unified messaging API.
      *
      * **Transport Selection Logic**:
-     * - **postMessage**: Used when game is in iframe AND sending to parent
-     * - **CustomEvent**: Used for all other cases (local development, parent-to-game)
+     * - **postMessage**: Used when game is in iframe AND sending to parent, OR when target window is specified
+     * - **CustomEvent**: Used for all other cases (local development, same-context communication)
      *
      * **Security Considerations**:
      * The origin is currently set to '*' for development convenience, but should be

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@playcademy/sdk",
     "type": "module",
-    "version": "0.0.1-beta.19",
+    "version": "0.0.1-beta.20",
     "exports": {
         ".": {
             "import": "./dist/index.js",