@playcademy/sdk 0.0.1-beta.17 → 0.0.1-beta.18

package/dist/index.d.ts

@@ -5,5 +5,5 @@
  * providing access to the main client class and supporting utilities.
  */
 export { PlaycademyClient } from './core/client';
-export { bus, BusEvents } from './bus';
+export { messaging, MessageEvents } from './messaging';
 export type * from './types';

package/dist/index.js

@@ -103,60 +103,92 @@ function createAuthNamespace(client) {
   };
 }
 
-// src/bus.ts
-var BusEvents, busListeners, bus;
-var init_bus = __esm(() => {
-  ((BusEvents2) => {
-    BusEvents2["INIT"] = "PLAYCADEMY_INIT";
-    BusEvents2["TOKEN_REFRESH"] = "PLAYCADEMY_TOKEN_REFRESH";
-    BusEvents2["PAUSE"] = "PLAYCADEMY_PAUSE";
-    BusEvents2["RESUME"] = "PLAYCADEMY_RESUME";
-    BusEvents2["FORCE_EXIT"] = "PLAYCADEMY_FORCE_EXIT";
-    BusEvents2["OVERLAY"] = "PLAYCADEMY_OVERLAY";
-    BusEvents2["READY"] = "PLAYCADEMY_READY";
-    BusEvents2["EXIT"] = "PLAYCADEMY_EXIT";
-    BusEvents2["TELEMETRY"] = "PLAYCADEMY_TELEMETRY";
-  })(BusEvents ||= {});
-  busListeners = new Map;
-  bus = {
-    emit(type, payload) {
-      const isIframe = typeof window !== "undefined" && window.self !== window.top;
-      const iframeToParentEvents = [
-        "PLAYCADEMY_READY" /* READY */,
-        "PLAYCADEMY_EXIT" /* EXIT */,
-        "PLAYCADEMY_TELEMETRY" /* TELEMETRY */
-      ];
-      if (isIframe && iframeToParentEvents.includes(type)) {
-        let messageData = { type };
-        if (payload !== undefined && typeof payload === "object" && payload !== null) {
-          messageData = { ...messageData, ...payload };
-        }
-        window.parent.postMessage(messageData, "*");
-      } else {
-        window.dispatchEvent(new CustomEvent(type, { detail: payload }));
-      }
-    },
-    on(type, handler) {
-      const listener = (event) => handler(event.detail);
-      if (!busListeners.has(type)) {
-        busListeners.set(type, new Map);
-      }
-      busListeners.get(type).set(handler, listener);
-      window.addEventListener(type, listener);
-    },
-    off(type, handler) {
-      const typeListeners = busListeners.get(type);
-      if (!typeListeners || !typeListeners.has(handler)) {
-        return;
-      }
-      const actualListener = typeListeners.get(handler);
-      window.removeEventListener(type, actualListener);
-      typeListeners.delete(handler);
-      if (typeListeners.size === 0) {
-        busListeners.delete(type);
+// src/messaging.ts
+class PlaycademyMessaging {
+  listeners = new Map;
+  send(type, payload) {
+    const context = this.getMessagingContext(type);
+    if (context.shouldUsePostMessage) {
+      this.sendViaPostMessage(type, payload, context.target, context.origin);
+    } else {
+      this.sendViaCustomEvent(type, payload);
+    }
+  }
+  listen(type, handler) {
+    const postMessageListener = (event) => {
+      const messageEvent = event;
+      if (messageEvent.data?.type === type) {
+        handler(messageEvent.data.payload || messageEvent.data);
       }
+    };
+    const customEventListener = (event) => {
+      handler(event.detail);
+    };
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, new Map);
     }
-  };
+    const listenerMap = this.listeners.get(type);
+    listenerMap.set(handler, {
+      postMessage: postMessageListener,
+      customEvent: customEventListener
+    });
+    window.addEventListener("message", postMessageListener);
+    window.addEventListener(type, customEventListener);
+  }
+  unlisten(type, handler) {
+    const typeListeners = this.listeners.get(type);
+    if (!typeListeners || !typeListeners.has(handler)) {
+      return;
+    }
+    const listeners = typeListeners.get(handler);
+    window.removeEventListener("message", listeners.postMessage);
+    window.removeEventListener(type, listeners.customEvent);
+    typeListeners.delete(handler);
+    if (typeListeners.size === 0) {
+      this.listeners.delete(type);
+    }
+  }
+  getMessagingContext(eventType) {
+    const isIframe = typeof window !== "undefined" && window.self !== window.top;
+    const iframeToParentEvents = [
+      "PLAYCADEMY_READY" /* READY */,
+      "PLAYCADEMY_EXIT" /* EXIT */,
+      "PLAYCADEMY_TELEMETRY" /* TELEMETRY */
+    ];
+    const shouldUsePostMessage = isIframe && iframeToParentEvents.includes(eventType);
+    return {
+      shouldUsePostMessage,
+      target: shouldUsePostMessage ? window.parent : undefined,
+      origin: "*"
+    };
+  }
+  sendViaPostMessage(type, payload, target = window.parent, origin = "*") {
+    let messageData = { type };
+    if (payload !== undefined && typeof payload === "object" && payload !== null) {
+      messageData = { ...messageData, ...payload };
+    } else if (payload !== undefined) {
+      messageData.payload = payload;
+    }
+    target.postMessage(messageData, origin);
+  }
+  sendViaCustomEvent(type, payload) {
+    window.dispatchEvent(new CustomEvent(type, { detail: payload }));
+  }
+}
+var MessageEvents, messaging;
+var init_messaging = __esm(() => {
+  ((MessageEvents2) => {
+    MessageEvents2["INIT"] = "PLAYCADEMY_INIT";
+    MessageEvents2["TOKEN_REFRESH"] = "PLAYCADEMY_TOKEN_REFRESH";
+    MessageEvents2["PAUSE"] = "PLAYCADEMY_PAUSE";
+    MessageEvents2["RESUME"] = "PLAYCADEMY_RESUME";
+    MessageEvents2["FORCE_EXIT"] = "PLAYCADEMY_FORCE_EXIT";
+    MessageEvents2["OVERLAY"] = "PLAYCADEMY_OVERLAY";
+    MessageEvents2["READY"] = "PLAYCADEMY_READY";
+    MessageEvents2["EXIT"] = "PLAYCADEMY_EXIT";
+    MessageEvents2["TELEMETRY"] = "PLAYCADEMY_TELEMETRY";
+  })(MessageEvents ||= {});
+  messaging = new PlaycademyMessaging;
 });
 
 // src/core/namespaces/runtime.ts
@@ -177,12 +209,12 @@ function createRuntimeNamespace(client) {
           console.error("[SDK] Failed to auto-end session:", client["internalClientSessionId"], error);
         }
       }
-      bus.emit("PLAYCADEMY_EXIT" /* EXIT */, undefined);
+      messaging.send("PLAYCADEMY_EXIT" /* EXIT */, undefined);
     }
   };
 }
 var init_runtime = __esm(() => {
-  init_bus();
+  init_messaging();
 });
 
 // src/core/namespaces/games.ts
@@ -394,15 +426,15 @@ async function init() {
     token: config.token,
     gameId: config.gameId
   });
-  bus.on("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, ({ token }) => client.setToken(token));
-  bus.emit("PLAYCADEMY_READY" /* READY */, undefined);
+  messaging.listen("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, ({ token }) => client.setToken(token));
+  messaging.send("PLAYCADEMY_READY" /* READY */, undefined);
   if (import.meta.env?.MODE === "development") {
     window.PLAYCADEMY_CLIENT = client;
   }
   return client;
 }
 var init_init = __esm(() => {
-  init_bus();
+  init_messaging();
 });
 
 // src/core/static/login.ts
@@ -542,9 +574,9 @@ var init_client = __esm(() => {
 
 // src/index.ts
 init_client();
-init_bus();
+init_messaging();
 export {
-  bus,
+  messaging,
   PlaycademyClient,
-  BusEvents
+  MessageEvents
 };

package/dist/messaging.d.ts

@@ -0,0 +1,496 @@
+/**
+ * @fileoverview Playcademy Messaging System
+ *
+ * This file implements a unified messaging system for the Playcademy platform that handles
+ * communication between different contexts:
+ *
+ * 1. **Iframe-to-Parent Communication**: When games run inside iframes (production/development),
+ *    they need to communicate with the parent window using postMessage API
+ *
+ * 2. **Local Communication**: When games run in the same context (local development),
+ *    they use CustomEvents for internal messaging
+ *
+ * The system automatically detects the runtime environment and chooses the appropriate
+ * transport method, abstracting this complexity from the developer.
+ *
+ * **Architecture Overview**:
+ * - Games run in iframes for security and isolation
+ * - Parent window (Playcademy shell) manages game lifecycle
+ * - Messages flow bidirectionally between parent and iframe
+ * - Local development mode simulates this architecture without iframes
+ */
+import type { GameContextPayload } from './types';
+/**
+ * Enumeration of all message types used in the Playcademy messaging system.
+ *
+ * **Message Flow Patterns**:
+ *
+ * **Parent → Game (Overworld → Game)**:
+ * - INIT: Provides game with authentication token and configuration
+ * - TOKEN_REFRESH: Updates game's authentication token before expiry
+ * - PAUSE/RESUME: Controls game execution state
+ * - FORCE_EXIT: Immediately terminates the game
+ * - OVERLAY: Shows/hides UI overlays over the game
+ *
+ * **Game → Parent (Game → Overworld)**:
+ * - READY: Game has loaded and is ready to receive messages
+ * - EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
+ * - TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)
+ */
+export declare enum MessageEvents {
+    /**
+     * Initializes the game with authentication context and configuration.
+     * Sent immediately after game iframe loads.
+     * Payload: { baseUrl: string, token: string, gameId: string }
+     */
+    INIT = "PLAYCADEMY_INIT",
+    /**
+     * Updates the game's authentication token before it expires.
+     * Sent periodically to maintain valid authentication.
+     * Payload: { token: string, exp: number }
+     */
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
+    /**
+     * Pauses game execution (e.g., when user switches tabs).
+     * Game should pause timers, animations, and user input.
+     * Payload: void
+     */
+    PAUSE = "PLAYCADEMY_PAUSE",
+    /**
+     * Resumes game execution after being paused.
+     * Game should restore timers, animations, and user input.
+     * Payload: void
+     */
+    RESUME = "PLAYCADEMY_RESUME",
+    /**
+     * Forces immediate game termination (emergency exit).
+     * Game should clean up resources and exit immediately.
+     * Payload: void
+     */
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
+    /**
+     * Shows or hides UI overlays over the game.
+     * Game may need to pause or adjust rendering accordingly.
+     * Payload: boolean (true = show overlay, false = hide overlay)
+     */
+    OVERLAY = "PLAYCADEMY_OVERLAY",
+    /**
+     * Game has finished loading and is ready to receive messages.
+     * Sent once after game initialization is complete.
+     * Payload: void
+     */
+    READY = "PLAYCADEMY_READY",
+    /**
+     * Game requests to be closed/exited.
+     * Sent when user clicks exit button or game naturally ends.
+     * Payload: void
+     */
+    EXIT = "PLAYCADEMY_EXIT",
+    /**
+     * Game reports performance telemetry data.
+     * Sent periodically for monitoring and analytics.
+     * Payload: { fps: number, mem: number }
+     */
+    TELEMETRY = "PLAYCADEMY_TELEMETRY"
+}
+/**
+ * Type definition for message handler functions.
+ * These functions are called when a specific message type is received.
+ *
+ * @template T - The type of payload data the handler expects
+ * @param payload - The data sent with the message
+ */
+type MessageHandler<T = unknown> = (payload: T) => void;
+/**
+ * Type mapping that defines the payload structure for each message type.
+ * This ensures type safety when sending and receiving messages.
+ *
+ * **Usage Examples**:
+ * ```typescript
+ * // Type-safe message sending
+ * messaging.send(MessageEvents.INIT, { baseUrl: '/api', token: 'abc', gameId: '123' })
+ *
+ * // Type-safe message handling
+ * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+ *   console.log(`New token expires at: ${new Date(exp)}`)
+ * })
+ * ```
+ */
+export type MessageEventMap = {
+    /** Game initialization context with API endpoint, auth token, and game ID */
+    [MessageEvents.INIT]: GameContextPayload;
+    /** Token refresh data with new token and expiration timestamp */
+    [MessageEvents.TOKEN_REFRESH]: {
+        token: string;
+        exp: number;
+    };
+    /** Pause message has no payload data */
+    [MessageEvents.PAUSE]: void;
+    /** Resume message has no payload data */
+    [MessageEvents.RESUME]: void;
+    /** Force exit message has no payload data */
+    [MessageEvents.FORCE_EXIT]: void;
+    /** Overlay visibility state (true = show, false = hide) */
+    [MessageEvents.OVERLAY]: boolean;
+    /** Ready message has no payload data */
+    [MessageEvents.READY]: void;
+    /** Exit message has no payload data */
+    [MessageEvents.EXIT]: void;
+    /** Performance telemetry data */
+    [MessageEvents.TELEMETRY]: {
+        fps: number;
+        mem: number;
+    };
+};
+/**
+ * **PlaycademyMessaging Class**
+ *
+ * This is the core messaging system that handles all communication in the Playcademy platform.
+ * It automatically detects the runtime environment and chooses the appropriate transport method.
+ *
+ * **Key Features**:
+ * 1. **Automatic Transport Selection**: Detects iframe vs local context and uses appropriate method
+ * 2. **Type Safety**: Full TypeScript support with payload type checking
+ * 3. **Bidirectional Communication**: Handles both parent→game and game→parent messages
+ * 4. **Event Cleanup**: Proper listener management to prevent memory leaks
+ *
+ * **Transport Methods**:
+ * - **postMessage**: Used for iframe-to-parent communication (production/development)
+ * - **CustomEvent**: Used for local same-context communication (local development)
+ *
+ * **Runtime Detection Logic**:
+ * - If `window.self !== window.top`: We're in an iframe, use postMessage
+ * - If `window.self === window.top`: We're in the same context, use CustomEvent
+ *
+ * **Example Usage**:
+ * ```typescript
+ * // Send a message (automatically chooses transport)
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for messages (handles both transports)
+ * messaging.listen(MessageEvents.INIT, (payload) => {
+ *   console.log('Game initialized with:', payload)
+ * })
+ *
+ * // Clean up listeners
+ * messaging.unlisten(MessageEvents.INIT, handler)
+ * ```
+ */
+declare class PlaycademyMessaging {
+    /**
+     * Internal storage for message listeners.
+     *
+     * **Structure Explanation**:
+     * - Outer Map: MessageEvents → Map of handlers for that event type
+     * - Inner Map: MessageHandler → Object containing both listener types
+     * - Object: { postMessage: EventListener, customEvent: EventListener }
+     *
+     * **Why Two Listeners Per Handler?**:
+     * Since we don't know at registration time which transport will be used,
+     * we register both a postMessage listener and a CustomEvent listener.
+     * The appropriate one will be triggered based on the runtime context.
+     */
+    private listeners;
+    /**
+     * **Send Message Method**
+     *
+     * Sends a message using the appropriate transport method based on the runtime context.
+     * This is the main public API for sending messages in the Playcademy system.
+     *
+     * **How It Works**:
+     * 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 game is in iframe and sending to parent
+     * - **CustomEvent**: Used for local/same-context communication
+     *
+     * **Type Safety**:
+     * The generic type parameter `K` ensures that the payload type matches
+     * the expected type for the given message event.
+     *
+     * @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)
+     *
+     * @example
+     * ```typescript
+     * // Send game ready signal (no payload)
+     * messaging.send(MessageEvents.READY, undefined)
+     *
+     * // Send telemetry data (typed payload)
+     * 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]): void;
+    /**
+     * **Listen for Messages Method**
+     *
+     * Registers a message listener that will be called when the specified message type is received.
+     * This method automatically handles both postMessage and CustomEvent sources.
+     *
+     * **Why Register Two Listeners?**:
+     * Since we don't know at registration time which transport method will be used to send
+     * messages, we register listeners for both possible sources:
+     * 1. **postMessage listener**: Handles messages from iframe-to-parent communication
+     * 2. **CustomEvent listener**: Handles messages from local same-context communication
+     *
+     * **Message Processing**:
+     * - **postMessage**: Extracts data from `event.data.payload` or `event.data`
+     * - **CustomEvent**: Extracts data from `event.detail`
+     *
+     * **Type Safety**:
+     * The handler function receives the correctly typed payload based on the message type.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to listen for
+     * @param handler - Function to call when the message is received
+     *
+     * @example
+     * ```typescript
+     * // Listen for game initialization
+     * messaging.listen(MessageEvents.INIT, (payload) => {
+     *   // payload is automatically typed as GameContextPayload
+     *   console.log(`Game ${payload.gameId} initialized`)
+     *   console.log(`API base URL: ${payload.baseUrl}`)
+     * })
+     *
+     * // Listen for token refresh
+     * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+     *   // payload is automatically typed as { token: string; exp: number }
+     *   updateAuthToken(token)
+     *   scheduleTokenRefresh(exp)
+     * })
+     * ```
+     */
+    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    /**
+     * **Remove Message Listener Method**
+     *
+     * Removes a previously registered message listener to prevent memory leaks and unwanted callbacks.
+     * This method cleans up both the postMessage and CustomEvent listeners that were registered.
+     *
+     * **Why Clean Up Both Listeners?**:
+     * When we registered the listener with `listen()`, we created two browser event listeners:
+     * 1. A 'message' event listener for postMessage communication
+     * 2. A custom event listener for local CustomEvent communication
+     *
+     * Both must be removed to prevent memory leaks and ensure the handler is completely unregistered.
+     *
+     * **Memory Management**:
+     * - Removes both event listeners from the browser
+     * - Cleans up internal tracking maps
+     * - If no more handlers exist for a message type, removes the entire type entry
+     *
+     * **Safe to Call Multiple Times**:
+     * This method is idempotent - calling it multiple times with the same handler is safe.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to stop listening for
+     * @param handler - The exact handler function that was passed to listen()
+     *
+     * @example
+     * ```typescript
+     * // Register a handler
+     * const handleInit = (payload) => console.log('Game initialized')
+     * messaging.listen(MessageEvents.INIT, handleInit)
+     *
+     * // Later, remove the handler
+     * messaging.unlisten(MessageEvents.INIT, handleInit)
+     *
+     * // Safe to call multiple times
+     * messaging.unlisten(MessageEvents.INIT, handleInit) // No error
+     * ```
+     */
+    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    /**
+     * **Get Messaging Context Method**
+     *
+     * Analyzes the current runtime environment and message type to determine the appropriate
+     * transport method and configuration for sending messages.
+     *
+     * **Runtime Environment Detection**:
+     * The method detects whether the code is running in an iframe by comparing:
+     * - `window.self`: Reference to the current window
+     * - `window.top`: Reference to the topmost window in the hierarchy
+     *
+     * If they're different, we're in an iframe. If they're the same, we're in the top-level window.
+     *
+     * **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)
+     *
+     * **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)
+     *
+     * **Security Considerations**:
+     * The origin is currently set to '*' for development convenience, but should be
+     * configurable for production security.
+     *
+     * @param eventType - The message event type being sent
+     * @returns Configuration object with transport method and target information
+     *
+     * @example
+     * ```typescript
+     * // In iframe sending READY to parent
+     * const context = getMessagingContext(MessageEvents.READY)
+     * // Returns: { shouldUsePostMessage: true, target: window.parent, origin: '*' }
+     *
+     * // In same context sending INIT
+     * const context = getMessagingContext(MessageEvents.INIT)
+     * // Returns: { shouldUsePostMessage: false, target: undefined, origin: '*' }
+     * ```
+     */
+    private getMessagingContext;
+    /**
+     * **Send Via PostMessage Method**
+     *
+     * Sends a message using the browser's postMessage API for iframe-to-parent communication.
+     * This method is used when the game is running in an iframe and needs to communicate
+     * with the parent window (the Playcademy shell).
+     *
+     * **PostMessage Protocol**:
+     * The postMessage API is the standard way for iframes to communicate with their parent.
+     * It's secure, cross-origin capable, and designed specifically for this use case.
+     *
+     * **Message Structure**:
+     * The method creates a message object with the following structure:
+     * - `type`: The message event type (e.g., 'PLAYCADEMY_READY')
+     * - Payload data: Either spread into the object or in a `payload` property
+     *
+     * **Payload Handling**:
+     * - **Object payloads**: Spread directly into the message (e.g., { type, token, exp })
+     * - **Primitive payloads**: Wrapped in a `payload` property (e.g., { type, payload: true })
+     * - **Undefined payloads**: Only the type is sent (e.g., { type })
+     *
+     * **Security**:
+     * The origin parameter controls which domains can receive the message.
+     * Currently set to '*' for development, but should be restricted in production.
+     *
+     * @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
+     * @param target - The target window (defaults to parent window)
+     * @param origin - The allowed origin for the message (defaults to '*')
+     *
+     * @example
+     * ```typescript
+     * // Send ready signal (no payload)
+     * sendViaPostMessage(MessageEvents.READY, undefined)
+     * // Sends: { type: 'PLAYCADEMY_READY' }
+     *
+     * // Send telemetry data (object payload)
+     * sendViaPostMessage(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
+     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', fps: 60, mem: 128 }
+     *
+     * // Send overlay state (primitive payload)
+     * sendViaPostMessage(MessageEvents.OVERLAY, true)
+     * // Sends: { type: 'PLAYCADEMY_OVERLAY', payload: true }
+     * ```
+     */
+    private sendViaPostMessage;
+    /**
+     * **Send Via CustomEvent Method**
+     *
+     * Sends a message using the browser's CustomEvent API for local same-context communication.
+     * This method is used when both the sender and receiver are in the same window context,
+     * typically during local development or when the parent needs to send messages to the game.
+     *
+     * **CustomEvent Protocol**:
+     * CustomEvent is a browser API for creating and dispatching custom events within the same
+     * window context. It's simpler than postMessage but only works within the same origin/context.
+     *
+     * **Event Structure**:
+     * - **type**: The event name (e.g., 'PLAYCADEMY_INIT')
+     * - **detail**: The payload data attached to the event
+     *
+     * **When This Is Used**:
+     * - Local development when game and shell run in the same context
+     * - Parent-to-game communication (INIT, TOKEN_REFRESH, PAUSE, etc.)
+     * - Any scenario where postMessage isn't needed
+     *
+     * **Event Bubbling**:
+     * CustomEvents are dispatched on the window object and can be listened to by any
+     * code in the same context using `addEventListener(type, handler)`.
+     *
+     * @template K - The message event type (ensures type safety)
+     * @param type - The message event type to send (becomes the event name)
+     * @param payload - The data to send with the message (stored in event.detail)
+     *
+     * @example
+     * ```typescript
+     * // Send initialization data
+     * sendViaCustomEvent(MessageEvents.INIT, {
+     *   baseUrl: '/api',
+     *   token: 'abc123',
+     *   gameId: 'game-456'
+     * })
+     * // Creates: CustomEvent('PLAYCADEMY_INIT', { detail: { baseUrl, token, gameId } })
+     *
+     * // Send pause signal
+     * sendViaCustomEvent(MessageEvents.PAUSE, undefined)
+     * // Creates: CustomEvent('PLAYCADEMY_PAUSE', { detail: undefined })
+     *
+     * // Listeners can access the data via event.detail:
+     * window.addEventListener('PLAYCADEMY_INIT', (event) => {
+     *   console.log(event.detail.gameId) // 'game-456'
+     * })
+     * ```
+     */
+    private sendViaCustomEvent;
+}
+/**
+ * **Playcademy Messaging Singleton**
+ *
+ * This is the main messaging instance used throughout the Playcademy platform.
+ * It's exported as a singleton to ensure consistent communication across all parts
+ * of the application.
+ *
+ * **Why a Singleton?**:
+ * - Ensures all parts of the app use the same messaging instance
+ * - Prevents conflicts between multiple messaging systems
+ * - Simplifies the API - no need to pass instances around
+ * - Maintains consistent event listener management
+ *
+ * **Usage in Different Contexts**:
+ *
+ * **In Games**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Tell parent we're ready
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for pause/resume
+ * messaging.listen(MessageEvents.PAUSE, () => game.pause())
+ * messaging.listen(MessageEvents.RESUME, () => game.resume())
+ * ```
+ *
+ * **In Parent Shell**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Send initialization data to game
+ * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId })
+ *
+ * // Listen for game events
+ * messaging.listen(MessageEvents.EXIT, () => closeGame())
+ * messaging.listen(MessageEvents.READY, () => showGame())
+ * ```
+ *
+ * **Automatic Transport Selection**:
+ * The messaging system automatically chooses the right transport method:
+ * - Uses postMessage when game is in iframe sending to parent
+ * - Uses CustomEvent for local development and parent-to-game communication
+ *
+ * **Type Safety**:
+ * All message sending and receiving is fully type-safe with TypeScript.
+ */
+export declare const messaging: PlaycademyMessaging;
+export {};

package/package.json

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

package/dist/bus.d.ts

@@ -1,37 +0,0 @@
-import type { GameContextPayload } from './types';
-export declare enum BusEvents {
-    INIT = "PLAYCADEMY_INIT",
-    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
-    PAUSE = "PLAYCADEMY_PAUSE",
-    RESUME = "PLAYCADEMY_RESUME",
-    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
-    OVERLAY = "PLAYCADEMY_OVERLAY",
-    READY = "PLAYCADEMY_READY",
-    EXIT = "PLAYCADEMY_EXIT",
-    TELEMETRY = "PLAYCADEMY_TELEMETRY"
-}
-type BusHandler<T = unknown> = (payload: T) => void;
-export type BusEventMap = {
-    [BusEvents.INIT]: GameContextPayload;
-    [BusEvents.TOKEN_REFRESH]: {
-        token: string;
-        exp: number;
-    };
-    [BusEvents.PAUSE]: void;
-    [BusEvents.RESUME]: void;
-    [BusEvents.FORCE_EXIT]: void;
-    [BusEvents.OVERLAY]: boolean;
-    [BusEvents.READY]: void;
-    [BusEvents.EXIT]: void;
-    [BusEvents.TELEMETRY]: {
-        fps: number;
-        mem: number;
-    };
-};
-interface Bus {
-    emit<K extends BusEvents>(type: K, payload: BusEventMap[K]): void;
-    on<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>): void;
-    off<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>): void;
-}
-export declare const bus: Bus;
-export {};