@playcademy/sdk 0.5.0 → 0.6.0-beta.1

package/dist/index.d.ts

@@ -534,6 +534,23 @@ interface UserInfo {
     lti_resource_link?: unknown;
     timeback_id?: string;
 }
+interface DemoProfile {
+    displayName: string;
+    isDefault: boolean;
+}
+/**
+ * Update shape for `client.demo.profile.update(...)`.
+ *
+ * Kept as a named type so callers typed against it pick up new fields
+ * automatically, but `displayName` is the only updatable field today and
+ * the server's `DemoProfileSchema` requires it — a no-field payload would
+ * 400 at runtime, so we model that at the type level too. When additional
+ * fields land, make them required/optional individually based on server
+ * validation, rather than blanket-optional.
+ */
+interface DemoProfileUpdate {
+    displayName: string;
+}
 /**
  * Authenticated user for API responses.
  * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
@@ -554,6 +571,35 @@ interface AuthenticatedUser {
     timeback?: UserTimebackData;
 }
 
+/**
+ * Leaderboard Types
+ *
+ * @module types/leaderboard
+ */
+type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
+interface LeaderboardOptions {
+    timeframe?: LeaderboardTimeframe;
+    limit?: number;
+    offset?: number;
+    gameId?: string;
+}
+/**
+ * Leaderboard entry with required game context.
+ * Used when fetching leaderboards for a specific game.
+ */
+interface GameLeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
+
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
     schema: undefined;
@@ -830,195 +876,6 @@ type InventoryItemWithItem = InventoryItemRow & {
     item: ItemRow;
 };
 
-/**
- * @fileoverview Authentication Strategy Pattern
- *
- * Provides different authentication strategies for the Playcademy SDK.
- * Each strategy knows how to add its authentication headers to requests.
- */
-
-/**
- * Base interface for authentication strategies
- */
-interface AuthStrategy {
-    /** Get the token value */
-    getToken(): string | null;
-    /** Get the token type */
-    getType(): TokenType;
-    /** Get authentication headers for a request */
-    getHeaders(): Record<string, string>;
-}
-
-/**
- * Base Playcademy SDK client with shared infrastructure.
- * Provides authentication, HTTP requests, events, connection monitoring,
- * and fundamental namespaces used by all clients.
- *
- * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
- */
-declare abstract class PlaycademyBaseClient {
-    baseUrl: string;
-    gameUrl?: string;
-    protected authStrategy: AuthStrategy;
-    protected gameId?: string;
-    protected config: Partial<ClientConfig>;
-    protected listeners: EventListeners;
-    protected internalClientSessionId?: string;
-    protected authContext?: {
-        isInIframe: boolean;
-    };
-    protected initPayload?: InitPayload;
-    protected connectionManager?: ConnectionManager;
-    protected launchId?: string;
-    /**
-     * Internal session manager for automatic session lifecycle.
-     * @private
-     * @internal
-     */
-    protected _sessionManager: {
-        startSession: (gameId: string) => Promise<{
-            sessionId: string;
-        }>;
-        endSession: (sessionId: string, gameId: string) => Promise<void>;
-    };
-    constructor(config?: Partial<ClientConfig>);
-    /**
-     * Gets the effective base URL for API requests.
-     */
-    getBaseUrl(): string;
-    /**
-     * Gets the effective game backend URL for integration requests.
-     */
-    protected getGameBackendUrl(): string;
-    /**
-     * Simple ping method for testing connectivity.
-     */
-    ping(): string;
-    /**
-     * Sets the authentication token for API requests.
-     */
-    setToken(token: string | null, tokenType?: TokenType): void;
-    setLaunchId(launchId: string | null | undefined): void;
-    /**
-     * Gets the current token type.
-     */
-    getTokenType(): TokenType;
-    /**
-     * Gets the current authentication token.
-     */
-    getToken(): string | null;
-    /**
-     * Checks if the client has a valid API token.
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Registers a callback to be called when authentication state changes.
-     */
-    onAuthChange(callback: (token: string | null) => void): void;
-    /**
-     * Registers a callback to be called when connection issues are detected.
-     */
-    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
-    /**
-     * Gets the current connection state.
-     */
-    getConnectionState(): ConnectionState | 'unknown';
-    /**
-     * Manually triggers a connection check immediately.
-     */
-    checkConnection(): Promise<ConnectionState | 'unknown'>;
-    /**
-     * Sets the authentication context for the client.
-     * @internal
-     */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
-    /**
-     * Registers an event listener for client events.
-     */
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
-    /**
-     * Emits an event to all registered listeners.
-     */
-    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
-    /**
-     * Makes an authenticated HTTP request to the platform API.
-     */
-    protected request<T>(path: string, method: Method, options?: {
-        body?: unknown;
-        headers?: Record<string, string>;
-        raw?: boolean;
-        retryPolicy?: RetryPolicy;
-    }): Promise<T>;
-    /**
-     * Makes an authenticated HTTP request to the game's backend Worker.
-     */
-    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, options?: {
-        raw?: boolean;
-        retryPolicy?: RetryPolicy;
-    }): Promise<T>;
-    /**
-     * Ensures a gameId is available, throwing an error if not.
-     */
-    protected _ensureGameId(): string;
-    /**
-     * Detects and sets the authentication context (iframe vs standalone).
-     */
-    private _detectAuthContext;
-    /**
-     * Initializes connection monitoring if enabled.
-     */
-    private _initializeConnectionMonitor;
-    private _initializeInternalSession;
-    /**
-     * Current user data and inventory management.
-     * - `me()` - Get authenticated user profile
-     * - `inventory.get()` - List user's items
-     * - `inventory.add(slug, qty)` - Award items to user
-     */
-    users: {
-        me: () => Promise<AuthenticatedUser>;
-        inventory: {
-            get: () => Promise<InventoryItemWithItem[]>;
-            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
-            quantity: (identifier: string) => Promise<number>;
-            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
-        };
-    };
-}
-
-/**
- * Options for configuring activity tracking behavior.
- */
-interface StartActivityOptions {
-    /**
-     * How long the tab can stay hidden before the timing window resets on return.
-     * Defaults to 10 minutes. Set to `Infinity` to disable.
-     */
-    hiddenTimeoutMs?: number;
-    /**
-     * How often to flush periodic heartbeats with accumulated time data.
-     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
-     * final unload/endActivity flushes still run.
-     */
-    heartbeatIntervalMs?: number;
-    /**
-     * Stable identifier for this activity run. When provided, it is used on
-     * every heartbeat and on endActivity instead of a freshly-generated UUID.
-     *
-     * Pass the same `runId` across multiple `startActivity()` calls (for
-     * example, after the player closes and reopens a resumable activity) so
-     * downstream systems can correlate related sessions into a single run.
-     *
-     * Must be a UUID (the backend validates it as such) and unique per
-     * logical run. If omitted, the SDK generates a new UUID on each call,
-     * which means every session is treated as its own run.
-     */
-    runId?: string;
-}
-
 /**
  * Auto-initializes a PlaycademyClient with context from the environment.
  * Works in both iframe mode (production/development) and standalone mode (local dev).
@@ -1085,1271 +942,1531 @@ declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(thi
 declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
 
 /**
- * Playcademy SDK client for game developers.
- * Provides namespaced access to platform features for games running inside Cademy.
+ * @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
  */
-declare class PlaycademyClient extends PlaycademyBaseClient {
+
+/**
+ * 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.)
+ */
+declare enum MessageEvents {
     /**
-     * Connect external identity providers to the user's Playcademy account.
-     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
+     * Initializes the game with authentication context and configuration.
+     * Sent immediately after game iframe loads.
+     * Payload:
+     * - `baseUrl`: string
+     * - `token`: string
+     * - `gameId`: string
      */
-    identity: {
-        connect: (options: AuthOptions) => Promise<AuthResult>;
-        _getContext: () => {
-            isInIframe: boolean;
-        };
-    };
+    INIT = "PLAYCADEMY_INIT",
     /**
-     * Game runtime lifecycle and asset loading.
-     * - `exit()` - Return to Cademy hub
-     * - `getGameToken()` - Get short-lived auth token
-     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
-     * - `on('pause')`, `on('resume')` - Handle visibility changes
+     * Updates the game's authentication token before it expires.
+     * Sent periodically to maintain valid authentication.
+     * Payload:
+     * - `token`: string
+     * - `exp`: number
      */
-    runtime: {
-        getGameToken: (gameId: string, options?: {
-            apply?: boolean | undefined;
-        } | undefined) => Promise<GameTokenResponse>;
-        exit: () => Promise<void>;
-        onInit: (handler: (context: GameContextPayload) => void) => void;
-        onTokenRefresh: (handler: (data: {
-            token: string;
-            exp: number;
-        }) => void) => void;
-        onPause: (handler: () => void) => void;
-        onResume: (handler: () => void) => void;
-        onForceExit: (handler: () => void) => void;
-        onOverlay: (handler: (isVisible: boolean) => void) => void;
-        ready: () => void;
-        sendTelemetry: (data: {
-            fps: number;
-            mem: number;
-        }) => void;
-        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
-            token: string;
-            exp: number;
-        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
-        removeAllListeners: () => void;
-        getListenerCounts: () => Record<string, number>;
-        assets: {
-            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit | undefined) => Promise<Response>;
-            json: <T = unknown>(path: string) => Promise<T>;
-            blob: (path: string) => Promise<Blob>;
-            text: (path: string) => Promise<string>;
-            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
-        };
-    };
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
     /**
-     * TimeBack integration for activity tracking and user context.
-     *
-     * User context (cached from init, refreshable):
-     * - `user.role` - User's role (student, parent, teacher, etc.)
-     * - `user.enrollments` - Courses the player is enrolled in for this game
-     * - `user.organizations` - Schools/districts the player belongs to
-     * - `user.fetch()` - Refresh user context from server
-     *
-     * Activity tracking:
-     * - `startActivity(metadata)` - Begin tracking an activity
-     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
-     * - `endActivity(scoreData)` - Submit activity results to TimeBack
+     * Pauses game execution (e.g., when user switches tabs).
+     * Game should pause timers, animations, and user input.
+     * Payload: void
      */
-    timeback: {
-        readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData, options?: StartActivityOptions | undefined) => void;
-        pauseActivity: () => void;
-        resumeActivity: () => void;
-        endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
-    };
+    PAUSE = "PLAYCADEMY_PAUSE",
     /**
-     * Playcademy Credits (platform currency) management.
-     * - `get()` - Get user's credit balance
-     * - `add(amount)` - Award credits to user
+     * Resumes game execution after being paused.
+     * Game should restore timers, animations, and user input.
+     * Payload: void
      */
-    credits: {
-        balance: () => Promise<number>;
-        add: (amount: number) => Promise<number>;
-        spend: (amount: number) => Promise<number>;
-    };
+    RESUME = "PLAYCADEMY_RESUME",
     /**
-     * Game score submission and leaderboards.
-     * - `submit(gameId, score, metadata?)` - Record a game score
+     * Forces immediate game termination (emergency exit).
+     * Game should clean up resources and exit immediately.
+     * Payload: void
      */
-    scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
-    };
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
     /**
-     * Realtime multiplayer authentication.
-     * - `getToken()` - Get token for WebSocket/realtime connections
+     * 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)
      */
-    realtime: {
-        token: {
-            get: () => Promise<RealtimeTokenResponse>;
-        };
-    };
+    OVERLAY = "PLAYCADEMY_OVERLAY",
     /**
-     * Make requests to your game's custom backend API routes.
-     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
-     * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
+     * Broadcasts connection state changes to games.
+     * Sent by platform when network connectivity changes.
+     * Payload:
+     * - `state`: 'online' | 'offline' | 'degraded'
+     * - `reason`: string
      */
-    backend: {
-        get<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<Response>;
-        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-    };
-    /** Auto-initializes a PlaycademyClient with context from the environment */
-    static init: typeof init;
-    /** Authenticates a user with email and password */
-    static login: typeof login;
-    /** Static identity utilities for OAuth operations */
-    static identity: {
-        parseOAuthState: typeof parseOAuthState;
-    };
+    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
+    /**
+     * 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",
+    /**
+     * Game reports key events to parent.
+     * Sent when certain keys are pressed within the game iframe.
+     * Payload:
+     * - `key`: string
+     * - `code?`: string
+     * - `type`: 'keydown' | 'keyup'
+     */
+    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
+    /**
+     * Game requests platform to display an alert.
+     * Sent when connection issues are detected or other important events occur.
+     * Payload:
+     * - `message`: string
+     * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
+     */
+    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
+    /**
+     * Game signals that demo mode has ended.
+     * Sent when a demo experience reaches its CTA/upgrade boundary.
+     * Payload:
+     * - `score?`: number
+     * - `durationMs?`: number
+     * - `metadata?`: `Record<string, unknown>`
+     */
+    DEMO_END = "PLAYCADEMY_DEMO_END",
+    /**
+     * Notifies about authentication state changes.
+     * Can be sent in both directions depending on auth flow.
+     * Payload:
+     * - `authenticated`: boolean
+     * - `user`: UserInfo | null
+     * - `error`: Error | null
+     */
+    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
+    /**
+     * OAuth callback data from popup/new-tab windows.
+     * Sent from popup window back to parent after OAuth completes.
+     * Payload:
+     * - `code`: string (OAuth authorization code)
+     * - `state`: string (OAuth state for CSRF protection)
+     * - `error`: string | null (OAuth error if any)
+     */
+    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
 }
-
 /**
- * Type definitions for the game timeback namespace.
+ * Type definition for message handler functions.
+ * These functions are called when a specific message type is received.
  *
- * SDK-specific types like TimebackInitContext that wrap the core types
- * from @playcademy/types/user (which are re-exported via types/data.ts).
- */
-
-/**
- * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId.
+ * @template T - The type of payload data the handler expects
+ * @param payload - The data sent with the message
  */
-type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
+type MessageHandler<T = unknown> = (payload: T) => void;
 /**
- * A TimeBack organization (school/district) for the current user.
- * Alias for UserOrganization.
+ * 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)}`)
+ * })
+ * ```
  */
-type TimebackOrganization = UserOrganization;
+interface 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]: TokenRefreshPayload;
+    /** 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;
+    /** Connection state change from platform */
+    [MessageEvents.CONNECTION_STATE]: ConnectionStatePayload;
+    /** Ready message has no payload data */
+    [MessageEvents.READY]: void;
+    /** Exit message has no payload data */
+    [MessageEvents.EXIT]: void;
+    /** Performance telemetry data */
+    [MessageEvents.TELEMETRY]: TelemetryPayload;
+    /** Key event data */
+    [MessageEvents.KEY_EVENT]: KeyEventPayload;
+    /** Display alert request from game */
+    [MessageEvents.DISPLAY_ALERT]: DisplayAlertPayload;
+    /** Demo end signal from game */
+    [MessageEvents.DEMO_END]: DemoEndPayload;
+    /** Authentication state change notification */
+    [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
+    /** OAuth callback data from popup/new-tab windows */
+    [MessageEvents.AUTH_CALLBACK]: AuthCallbackPayload;
+}
 /**
- * TimeBack context passed during game initialization.
- * This is sent from the platform (cademy) to the game iframe via postMessage.
- */
-interface TimebackInitContext {
-    /** User's TimeBack ID */
-    id: string;
-    /** User's role in TimeBack (student, parent, teacher, etc.) */
-    role: TimebackUserRole;
-    /** User's enrollments for this game (one per grade/subject combo) */
-    enrollments: TimebackEnrollment[];
-    /** User's organizations (schools/districts) */
-    organizations: TimebackOrganization[];
-}
-/**
- * TimeBack user context with current data (may be stale from init).
- * Use `fetch()` to get fresh data from the server.
- */
-interface TimebackUserContext {
-    /** User's TimeBack ID */
-    id: string | undefined;
-    /** User's role in TimeBack (student, parent, teacher, etc.) */
-    role: TimebackUserRole | undefined;
-    /** User's enrollments for this game */
-    enrollments: TimebackEnrollment[];
-    /** User's organizations (schools/districts) */
-    organizations: TimebackOrganization[];
-}
-/**
- * XP data access for the current user.
- * Results are cached for 5 seconds to avoid redundant network requests.
+ * **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)
+ * ```
  */
-interface TimebackUserXp {
+declare class PlaycademyMessaging {
     /**
-     * Fetch XP data from the server.
-     * Returns XP for all courses in this game, or filter by grade/subject.
-     * Results are cached for 5 seconds (use `force: true` to bypass).
+     * Internal storage for message listeners.
      *
-     * @param options - Query options
-     * @param options.grade - Grade level to filter (must be used with subject)
-     * @param options.subject - Subject to filter (must be used with grade)
-     * @param options.include - Additional data to include: 'perCourse', 'today'
-     * @param options.force - Bypass cache and fetch fresh data (default: false)
-     * @returns Promise resolving to XP data
+     * **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, OR when target window is specified
+     * - **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)
+     * @param options - Optional configuration for message sending
      *
      * @example
      * ```typescript
-     * // Get total XP for all game courses
-     * const xp = await client.timeback.user.xp.fetch()
+     * // Send game ready signal (no payload)
+     * messaging.send(MessageEvents.READY, undefined)
      *
-     * // Get XP for a specific grade/subject
-     * const xp = await client.timeback.user.xp.fetch({
-     *   grade: 3,
-     *   subject: 'Math'
-     * })
+     * // Send telemetry data (typed payload)
+     * messaging.send(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
      *
-     * // Get XP with per-course breakdown
-     * const xp = await client.timeback.user.xp.fetch({
-     *   include: ['perCourse', 'today']
+     * // Send to specific iframe window (parent to iframe communication)
+     * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId }, {
+     *   target: iframe.contentWindow,
+     *   origin: '*'
      * })
      *
-     * // Force fresh data
-     * const xp = await client.timeback.user.xp.fetch({ force: true })
+     * // TypeScript will error if payload type is wrong
+     * messaging.send(MessageEvents.INIT, "wrong type") // ❌ Error
      * ```
      */
-    fetch(options?: GetXpOptions): Promise<XpResponse>;
-}
-/**
- * TimeBack user object with both cached getters and fetch method.
- */
-interface TimebackUser extends TimebackUserContext {
+    send<K extends MessageEvents>(type: K, payload: MessageEventMap[K], options?: {
+        target?: Window;
+        origin?: string;
+    }): void;
     /**
-     * Fetch TimeBack data from the server (cached for 5 min).
-     * Updates the cached values so subsequent property access returns fresh data.
-     * @param options - Cache options (pass { force: true } to bypass cache)
-     * @returns Promise resolving to fresh user context
+     * **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)
+     * })
+     * ```
      */
-    fetch(options?: {
-        force?: boolean;
-    }): Promise<TimebackUserContext>;
+    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
     /**
-     * XP data for the current user.
-     * Call `xp.fetch()` to get XP from the server.
+     * **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
+     * ```
      */
-    xp: TimebackUserXp;
-}
-/**
- * Options for querying student XP.
- */
-interface GetXpOptions {
-    /** Grade level to filter (must be used with subject) */
-    grade?: TimebackGrade;
-    /** Subject to filter (must be used with grade) */
-    subject?: TimebackSubject;
-    /** Additional data to include: 'perCourse', 'today' */
-    include?: ('perCourse' | 'today')[];
-    /** Bypass cache and fetch fresh data (default: false) */
-    force?: boolean;
-}
-/**
- * XP data for a single course.
- */
-interface CourseXp {
-    grade: TimebackGrade;
-    subject: TimebackSubject;
-    title: string;
-    totalXp: number;
-    todayXp?: number;
-}
-/**
- * Response from XP query.
- */
-interface XpResponse {
-    totalXp: number;
-    todayXp?: number;
-    courses?: CourseXp[];
-}
-
-/**
- * Core client configuration and lifecycle types
- */
-
-type TokenType = 'session' | 'apiKey' | 'gameJwt';
-interface ClientConfig {
-    baseUrl: string;
-    gameUrl?: string;
-    token?: string;
-    tokenType?: TokenType;
-    gameId?: string;
-    launchId?: string;
-    autoStartSession?: boolean;
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
-}
-/**
- * Handler called when connection state changes to offline or degraded.
- * Games can implement this to handle disconnects gracefully.
- */
-type DisconnectHandler = (context: DisconnectContext) => void | Promise<void>;
-/**
- * Context provided to disconnect handlers
- */
-interface DisconnectContext {
-    /** Current connection state */
-    state: 'offline' | 'degraded';
-    /** Reason for the disconnect */
-    reason: string;
-    /** Timestamp when disconnect was detected */
-    timestamp: number;
-    /** Utility to display a platform-level alert */
-    displayAlert: (message: string, options?: {
-        type?: 'info' | 'warning' | 'error';
-        duration?: number;
-    }) => void;
-}
-interface InitPayload {
-    /** Hub API base URL */
-    baseUrl: string;
-    /** Game deployment URL (serves both frontend assets and backend API) */
-    gameUrl?: string;
-    /** Short-lived game token */
-    token: string;
-    /** Game ID */
-    gameId: string;
-    /** Realtime WebSocket URL */
-    realtimeUrl?: string;
-    /** Timeback context (if user has a Timeback account) */
-    timeback?: TimebackInitContext;
-}
-interface GameContextPayload {
-    token: string;
-    baseUrl: string;
-    realtimeUrl: string;
-    gameId: string;
-    forwardKeys?: string[];
-}
-type EventListeners = {
-    [E in keyof ClientEvents]?: ((payload: ClientEvents[E]) => void)[];
-};
-interface ClientEvents {
-    authChange: {
-        token: string | null;
-    };
-    inventoryChange: {
-        itemId: string;
-        delta: number;
-        newTotal: number;
-    };
-    levelUp: {
-        oldLevel: number;
-        newLevel: number;
-        creditsAwarded: number;
-    };
-    xpGained: {
-        amount: number;
-        totalXP: number;
-        leveledUp: boolean;
-    };
-    connectionChange: {
-        state: 'online' | 'offline' | 'degraded';
-        reason: string;
-    };
-}
-
-/**
- * Event and message payload types for SDK messaging system
- */
-
-interface DisplayAlertPayload {
-    message: string;
-    options?: {
-        type?: 'info' | 'warning' | 'error';
-        duration?: number;
-    };
-}
-/**
- * Authentication state change event payload.
- * Used when authentication state changes in the application.
- */
-interface AuthStateChangePayload {
-    /** Whether the user is currently authenticated */
-    authenticated: boolean;
-    /** User information if authenticated, null otherwise */
-    user: UserInfo | null;
-    /** Error information if authentication failed */
-    error: Error | null;
-}
-/**
- * OAuth callback event payload.
- * Used when OAuth flow completes in popup/new-tab windows.
- */
-interface AuthCallbackPayload {
-    /** OAuth authorization code */
-    code: string;
-    /** OAuth state parameter for CSRF protection */
-    state: string;
-    /** Error message if OAuth flow failed */
-    error: string | null;
-}
-/**
- * Token refresh event payload.
- * Sent when authentication token is updated.
- */
-interface TokenRefreshPayload {
-    /** New authentication token */
-    token: string;
-    /** Token expiration timestamp */
-    exp: number;
-}
-/**
- * Telemetry event payload.
- * Performance metrics sent from the game.
- */
-interface TelemetryPayload {
-    /** Frames per second */
-    fps: number;
-    /** Memory usage in MB */
-    mem: number;
-}
-/**
- * Keyboard event payload.
- * Key events forwarded from the game.
- */
-interface KeyEventPayload {
-    /** Key value (e.g., 'Escape', 'F1') */
-    key: string;
-    /** Key code (optional) */
-    code?: string;
-    /** Event type */
-    type: 'keydown' | 'keyup';
-}
-/**
- * Connection state payload.
- * Broadcast from platform to games when connection changes.
- */
-interface ConnectionStatePayload {
-    state: 'online' | 'offline' | 'degraded';
-    reason: string;
+    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, or postMessage with target)
+     *
+     * **Cross-Context Communication**:
+     * 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, 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
+     * 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`: The message data (if any)
+     *
+     * **Payload Handling**:
+     * - **All payloads**: Wrapped in a `payload` property for consistency (e.g., { type, payload: data })
+     * - **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', payload: { 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;
 }
-
 /**
- * SDK-specific API response types
+ * **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.
  */
-interface LoginResponse {
-    token: string;
-}
-interface GameTokenResponse {
-    token: string;
-    exp: number;
-}
-interface InventoryMutationResponse {
-    newTotal: number;
-}
+declare const messaging: PlaycademyMessaging;
 
 /**
- * Realtime namespace types
- */
-/**
- * Response type for the realtime token API
+ * @fileoverview Authentication Strategy Pattern
+ *
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
  */
-interface RealtimeTokenResponse {
-    token: string;
-}
 
 /**
- * Scores namespace types
+ * Base interface for authentication strategies
  */
-interface ScoreSubmission {
-    id: string;
-    score: number;
-    achievedAt: Date;
+interface AuthStrategy {
+    /** Get the token value */
+    getToken(): string | null;
+    /** Get the token type */
+    getType(): TokenType;
+    /** Get authentication headers for a request */
+    getHeaders(): Record<string, string>;
 }
 
 /**
- * Authentication namespace types
+ * Base Playcademy SDK client with shared infrastructure.
+ * Provides authentication, HTTP requests, events, connection monitoring,
+ * and fundamental namespaces used by all clients.
+ *
+ * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
  */
-
-type AuthProviderType = (typeof AUTH_PROVIDER_IDS)[keyof typeof AUTH_PROVIDER_IDS];
-interface AuthOptions {
-    /** The identity provider to use for authentication */
-    provider: AuthProviderType;
-    /** The OAuth callback URL where your server handles the callback */
-    callbackUrl: string;
-    /** Authentication mode - auto detects best option based on context */
-    mode?: 'auto' | 'popup' | 'redirect';
-    /** Callback for authentication state changes */
-    onStateChange?: (state: AuthStateUpdate) => void;
-    /** Custom OAuth configuration (for users embedding the SDK outside of the Playcademy platform) */
-    oauth?: {
-        clientId: string;
-        authorizationEndpoint?: string;
-        tokenEndpoint?: string;
-        scope?: string;
+declare abstract class PlaycademyBaseClient {
+    baseUrl: string;
+    gameUrl?: string;
+    mode: PlaycademyMode;
+    protected authStrategy: AuthStrategy;
+    protected gameId?: string;
+    protected config: Partial<ClientConfig>;
+    protected listeners: EventListeners;
+    protected internalClientSessionId?: string;
+    protected authContext?: {
+        isInIframe: boolean;
     };
+    protected initPayload?: InitPayload;
+    protected connectionManager?: ConnectionManager;
+    protected launchId?: string;
     /**
-     * Optional custom data to encode in OAuth state parameter.
-     * By default, the SDK automatically includes playcademy_user_id and game_id.
-     * Use this to add additional custom data if needed.
+     * Internal session manager for automatic session lifecycle.
+     * @private
+     * @internal
      */
-    stateData?: Record<string, string>;
-}
-interface AuthStateUpdate {
-    /** Current status of the authentication flow */
-    status: 'opening_popup' | 'exchanging_token' | 'complete' | 'error';
-    /** Human-readable message about the current state */
-    message: string;
-    /** Error details if status is 'error' */
-    error?: Error;
-}
-interface AuthResult {
-    /** Whether authentication was successful */
-    success: boolean;
-    /** User information if authentication was successful */
-    user?: UserInfo;
-    /** Error if authentication failed */
-    error?: Error;
+    protected _sessionManager: {
+        startSession: (gameId: string) => Promise<{
+            sessionId: string;
+        }>;
+        endSession: (sessionId: string, gameId: string) => Promise<void>;
+    };
+    constructor(config?: Partial<ClientConfig>);
+    /**
+     * Gets the effective base URL for API requests.
+     */
+    getBaseUrl(): string;
+    /**
+     * Gets the effective game backend URL for integration requests.
+     */
+    protected getGameBackendUrl(): string;
+    /**
+     * Simple ping method for testing connectivity.
+     */
+    ping(): string;
+    /**
+     * Sets the authentication token for API requests.
+     */
+    setToken(token: string | null, tokenType?: TokenType): void;
+    setLaunchId(launchId: string | null | undefined): void;
+    /**
+     * Gets the current token type.
+     */
+    getTokenType(): TokenType;
+    /**
+     * Gets the current authentication token.
+     */
+    getToken(): string | null;
+    /**
+     * Checks if the client has a valid API token.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Registers a callback to be called when authentication state changes.
+     */
+    onAuthChange(callback: (token: string | null) => void): void;
+    /**
+     * Registers a callback to be called when connection issues are detected.
+     */
+    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    /**
+     * Gets the current connection state.
+     */
+    getConnectionState(): ConnectionState | 'unknown';
+    /**
+     * Manually triggers a connection check immediately.
+     */
+    checkConnection(): Promise<ConnectionState | 'unknown'>;
+    /**
+     * Sets the authentication context for the client.
+     * @internal
+     */
+    _setAuthContext(context: {
+        isInIframe: boolean;
+    }): void;
+    /**
+     * Registers an event listener for client events.
+     */
+    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
+    /**
+     * Emits an event to all registered listeners.
+     */
+    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
+    /**
+     * Makes an authenticated HTTP request to the platform API.
+     */
+    protected request<T>(path: string, method: Method, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        raw?: boolean;
+        retryPolicy?: RetryPolicy;
+    }): Promise<T>;
+    /**
+     * Makes an authenticated HTTP request to the game's backend Worker.
+     */
+    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, options?: {
+        raw?: boolean;
+        retryPolicy?: RetryPolicy;
+    }): Promise<T>;
+    /**
+     * Ensures a gameId is available, throwing an error if not.
+     */
+    protected _ensureGameId(): string;
+    /**
+     * Detects and sets the authentication context (iframe vs standalone).
+     */
+    private _detectAuthContext;
+    /**
+     * Initializes connection monitoring if enabled.
+     */
+    private _initializeConnectionMonitor;
+    private _initializeInternalSession;
+    /**
+     * Current user data and inventory management.
+     * - `me()` - Get authenticated user profile
+     * - `inventory.get()` - List user's items
+     * - `inventory.add(slug, qty)` - Award items to user
+     */
+    users: {
+        me: () => Promise<AuthenticatedUser>;
+        inventory: {
+            get: () => Promise<InventoryItemWithItem[]>;
+            add: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+            remove: (identifier: string, qty: number) => Promise<InventoryMutationResponse>;
+            quantity: (identifier: string) => Promise<number>;
+            has: (identifier: string, minQuantity?: number) => Promise<boolean>;
+        };
+    };
 }
 
-type DevUploadEvent = {
-    type: 'init';
-} | {
-    type: 's3Progress';
-    loaded: number;
-    total: number;
-    percent: number;
-} | {
-    type: 'finalizeStart';
-} | {
-    type: 'finalizeProgress';
-    percent: number;
-    currentFileLabel?: string;
-} | {
-    type: 'finalizeStatus';
-    message: string;
-} | {
-    type: 'complete';
-} | {
-    type: 'close';
-};
-interface DevUploadHooks {
-    onEvent?: (e: DevUploadEvent) => void;
-    onClose?: () => void;
+/**
+ * Options for configuring activity tracking behavior.
+ */
+interface StartActivityOptions {
+    /**
+     * How long the tab can stay hidden before the timing window resets on return.
+     * Defaults to 10 minutes. Set to `Infinity` to disable.
+     */
+    hiddenTimeoutMs?: number;
+    /**
+     * How often to flush periodic heartbeats with accumulated time data.
+     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
+     * final unload/endActivity flushes still run.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Stable identifier for this activity run. When provided, it is used on
+     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     *
+     * Pass the same `runId` across multiple `startActivity()` calls (for
+     * example, after the player closes and reopens a resumable activity) so
+     * downstream systems can correlate related sessions into a single run.
+     *
+     * Must be a UUID (the backend validates it as such) and unique per
+     * logical run. If omitted, the SDK generates a new UUID on each call,
+     * which means every session is treated as its own run.
+     */
+    runId?: string;
 }
 
 /**
- * Connection Manager
- *
- * Manages connection monitoring and integrates it with the Playcademy client.
- * Handles event wiring, state management, and disconnect callbacks.
- *
- * In iframe mode, disables local monitoring and listens to platform connection
- * state broadcasts instead (avoids duplicate heartbeats).
- */
-
-/**
- * Configuration for the ConnectionManager.
+ * Playcademy SDK client for game developers.
+ * Provides namespaced access to platform features for games running inside Cademy.
  */
-interface ConnectionManagerConfig {
-    /** Base URL for API requests (used for heartbeat pings) */
-    baseUrl: string;
-    /** Authentication context (iframe vs standalone) for alert routing */
-    authContext?: {
-        isInIframe: boolean;
+declare class PlaycademyClient extends PlaycademyBaseClient {
+    /**
+     * Connect external identity providers to the user's Playcademy account.
+     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
+     */
+    identity: {
+        connect: (options: AuthOptions) => Promise<AuthResult>;
+        _getContext: () => {
+            isInIframe: boolean;
+        };
     };
-    /** Handler to call when connection issues are detected */
-    onDisconnect?: DisconnectHandler;
-    /** Callback to emit connection change events to the client */
-    onConnectionChange?: (state: ConnectionState, reason: string) => void;
-}
-/**
- * Manages connection monitoring for the Playcademy client.
- *
- * The ConnectionManager serves as an integration layer between the low-level
- * ConnectionMonitor and the PlaycademyClient. It handles:
- * - Event wiring and coordination
- * - Disconnect callbacks with context
- * - Platform-level alert integration
- * - Request success/failure tracking
- *
- * This class is used internally by PlaycademyClient and typically not
- * instantiated directly by game developers.
- *
- * @see {@link ConnectionMonitor} for the underlying monitoring implementation
- * @see {@link PlaycademyClient.onDisconnect} for the public API
- */
-declare class ConnectionManager {
-    private monitor?;
-    private authContext?;
-    private disconnectHandler?;
-    private connectionChangeCallback?;
-    private currentState;
-    private additionalDisconnectHandlers;
     /**
-     * Creates a new ConnectionManager instance.
-     *
-     * @param config - Configuration options for the manager
-     *
-     * @example
-     * ```typescript
-     * const manager = new ConnectionManager({
-     *   baseUrl: 'https://api.playcademy.com',
-     *   authContext: { isInIframe: false },
-     *   onDisconnect: (context) => {
-     *     console.log(`Disconnected: ${context.state}`)
-     *   },
-     *   onConnectionChange: (state, reason) => {
-     *     console.log(`Connection changed: ${state}`)
-     *   }
-     * })
-     * ```
+     * Game runtime lifecycle and asset loading.
+     * - `exit()` - Return to Cademy hub
+     * - `getGameToken()` - Get short-lived auth token
+     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
+     * - `on('pause')`, `on('resume')` - Handle visibility changes
      */
-    constructor(config: ConnectionManagerConfig);
+    runtime: {
+        getGameToken: (gameId: string, options?: {
+            apply?: boolean | undefined;
+        } | undefined) => Promise<GameTokenResponse>;
+        exit: () => Promise<void>;
+        onInit: (handler: (context: GameContextPayload) => void) => void;
+        onTokenRefresh: (handler: (data: {
+            token: string;
+            exp: number;
+        }) => void) => void;
+        onPause: (handler: () => void) => void;
+        onResume: (handler: () => void) => void;
+        onForceExit: (handler: () => void) => void;
+        onOverlay: (handler: (isVisible: boolean) => void) => void;
+        ready: () => void;
+        sendTelemetry: (data: {
+            fps: number;
+            mem: number;
+        }) => void;
+        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
+            token: string;
+            exp: number;
+        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
+        removeAllListeners: () => void;
+        getListenerCounts: () => Record<string, number>;
+        assets: {
+            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+            fetch: (path: string, options?: RequestInit | undefined) => Promise<Response>;
+            json: <T = unknown>(path: string) => Promise<T>;
+            blob: (path: string) => Promise<Blob>;
+            text: (path: string) => Promise<string>;
+            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
+        };
+    };
     /**
-     * Gets the current connection state.
+     * TimeBack integration for activity tracking and user context.
      *
-     * @returns The current connection state ('online', 'offline', or 'degraded')
+     * User context (cached from init, refreshable):
+     * - `user.role` - User's role (student, parent, teacher, etc.)
+     * - `user.enrollments` - Courses the player is enrolled in for this game
+     * - `user.organizations` - Schools/districts the player belongs to
+     * - `user.fetch()` - Refresh user context from server
      *
-     * @example
-     * ```typescript
-     * const state = manager.getState()
-     * if (state === 'offline') {
-     *   console.log('No connection')
-     * }
-     * ```
+     * Activity tracking:
+     * - `startActivity(metadata)` - Begin tracking an activity
+     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
+     * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */
-    getState(): ConnectionState;
+    timeback: {
+        readonly user: TimebackUser;
+        startActivity: (metadata: ActivityData, options?: StartActivityOptions | undefined) => void;
+        pauseActivity: () => void;
+        resumeActivity: () => void;
+        endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
+    };
     /**
-     * Manually triggers a connection check immediately.
-     *
-     * Forces a heartbeat ping to verify the current connection status.
-     * Useful when you need to check connectivity before a critical operation.
-     *
-     * In iframe mode, this returns the last known state from platform.
-     *
-     * @returns Promise resolving to the current connection state
-     *
-     * @example
-     * ```typescript
-     * const state = await manager.checkNow()
-     * if (state === 'online') {
-     *   await performCriticalOperation()
-     * }
-     * ```
+     * Playcademy Credits (platform currency) management.
+     * - `get()` - Get user's credit balance
+     * - `add(amount)` - Award credits to user
      */
-    checkNow(): Promise<ConnectionState>;
+    credits: {
+        balance: () => Promise<number>;
+        add: (amount: number) => Promise<number>;
+        spend: (amount: number) => Promise<number>;
+    };
     /**
-     * Reports a successful API request to the connection monitor.
-     *
-     * This resets the consecutive failure counter and transitions from
-     * 'degraded' to 'online' state if applicable.
-     *
-     * Typically called automatically by the SDK's request wrapper.
-     * No-op in iframe mode (platform handles monitoring).
+     * Game score submission and leaderboards.
+     * - `submit(score, metadata?)` - Record a game score
      */
-    reportRequestSuccess(): void;
+    scores: {
+        submit: (score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
+    };
     /**
-     * Reports a failed API request to the connection monitor.
-     *
-     * Only network errors are tracked (not 4xx/5xx HTTP responses).
-     * After consecutive failures exceed the threshold, the state transitions
-     * to 'degraded' or 'offline'.
-     *
-     * Typically called automatically by the SDK's request wrapper.
-     * No-op in iframe mode (platform handles monitoring).
-     *
-     * @param error - The error from the failed request
+     * Read-only leaderboard access for the current game scope.
+     * - `fetch(options?)` - Fetch leaderboard entries
      */
-    reportRequestFailure(error: unknown): void;
+    leaderboard: {
+        fetch: (options?: LeaderboardOptions | undefined) => Promise<GameLeaderboardEntry[]>;
+    };
+    /**
+     * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
+     * so callers should gate on the mode before reaching in.
+     * - `profile.get()` - Read the anonymous demo player's profile
+     * - `profile.update(updates)` - Update the demo player's profile (today: the required `displayName`)
+     * - `end(score, options?)` - Signal to the parent shell that the demo has ended
+     */
+    demo: {
+        profile: {
+            get: () => Promise<DemoProfile>;
+            update: (updates: DemoProfileUpdate) => Promise<DemoProfile>;
+        };
+        end: (score: number, options?: DemoEndOptions | undefined) => void;
+    };
+    /**
+     * Realtime multiplayer authentication.
+     * - `getToken()` - Get token for WebSocket/realtime connections
+     */
+    realtime: {
+        token: {
+            get: () => Promise<RealtimeTokenResponse>;
+        };
+    };
+    /**
+     * Make requests to your game's custom backend API routes.
+     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
+     * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
+     */
+    backend: {
+        get<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<Response>;
+        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+    };
+    /** Auto-initializes a PlaycademyClient with context from the environment */
+    static init: typeof init;
+    /** Authenticates a user with email and password */
+    static login: typeof login;
+    /** Static identity utilities for OAuth operations */
+    static identity: {
+        parseOAuthState: typeof parseOAuthState;
+    };
+}
+
+/**
+ * Type definitions for the game timeback namespace.
+ *
+ * SDK-specific types like TimebackInitContext that wrap the core types
+ * from @playcademy/types/user (which are re-exported via types/data.ts).
+ */
+
+/**
+ * A TimeBack enrollment for the current game session.
+ * Alias for UserEnrollment without the optional gameId.
+ */
+type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
+/**
+ * A TimeBack organization (school/district) for the current user.
+ * Alias for UserOrganization.
+ */
+type TimebackOrganization = UserOrganization;
+/**
+ * TimeBack context passed during game initialization.
+ * This is sent from the platform (cademy) to the game iframe via postMessage.
+ */
+interface TimebackInitContext {
+    /** User's TimeBack ID */
+    id: string;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole;
+    /** User's enrollments for this game (one per grade/subject combo) */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
+}
+/**
+ * TimeBack user context with current data (may be stale from init).
+ * Use `fetch()` to get fresh data from the server.
+ */
+interface TimebackUserContext {
+    /** User's TimeBack ID */
+    id: string | undefined;
+    /** User's role in TimeBack (student, parent, teacher, etc.) */
+    role: TimebackUserRole | undefined;
+    /** User's enrollments for this game */
+    enrollments: TimebackEnrollment[];
+    /** User's organizations (schools/districts) */
+    organizations: TimebackOrganization[];
+}
+/**
+ * XP data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserXp {
     /**
-     * Registers a callback to be called when connection issues are detected.
-     *
-     * The callback only fires for 'offline' and 'degraded' states, not when
-     * recovering to 'online'. This provides a clean API for games to handle
-     * disconnect scenarios without being notified of every state change.
-     *
-     * Works in both iframe and standalone modes transparently.
+     * Fetch XP data from the server.
+     * Returns XP for all courses in this game, or filter by grade/subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
      *
-     * @param callback - Function to call when connection degrades
-     * @returns Cleanup function to unregister the callback
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse', 'today'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to XP data
      *
      * @example
      * ```typescript
-     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
-     *   if (state === 'offline') {
-     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
-     *     saveGameState()
-     *   }
+     * // Get total XP for all game courses
+     * const xp = await client.timeback.user.xp.fetch()
+     *
+     * // Get XP for a specific grade/subject
+     * const xp = await client.timeback.user.xp.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
      * })
      *
-     * // Later: cleanup() to unregister
-     * ```
-     */
-    onDisconnect(callback: DisconnectHandler): () => void;
-    /**
-     * Stops connection monitoring and performs cleanup.
+     * // Get XP with per-course breakdown
+     * const xp = await client.timeback.user.xp.fetch({
+     *   include: ['perCourse', 'today']
+     * })
      *
-     * Removes event listeners and clears heartbeat intervals.
-     * Should be called when the client is being destroyed.
+     * // Force fresh data
+     * const xp = await client.timeback.user.xp.fetch({ force: true })
+     * ```
      */
-    stop(): void;
+    fetch(options?: GetXpOptions): Promise<XpResponse>;
+}
+/**
+ * TimeBack user object with both cached getters and fetch method.
+ */
+interface TimebackUser extends TimebackUserContext {
     /**
-     * Sets up listener for platform connection state broadcasts (iframe mode only).
+     * Fetch TimeBack data from the server (cached for 5 min).
+     * Updates the cached values so subsequent property access returns fresh data.
+     * @param options - Cache options (pass { force: true } to bypass cache)
+     * @returns Promise resolving to fresh user context
      */
-    private _setupPlatformListener;
+    fetch(options?: {
+        force?: boolean;
+    }): Promise<TimebackUserContext>;
     /**
-     * Handles connection state changes from the monitor or platform.
-     *
-     * Coordinates between:
-     * 1. Emitting events to the client (for client.on('connectionChange'))
-     * 2. Calling the disconnect handler if configured
-     * 3. Calling any additional handlers registered via onDisconnect()
-     *
-     * @param state - The new connection state
-     * @param reason - Human-readable reason for the state change
+     * XP data for the current user.
+     * Call `xp.fetch()` to get XP from the server.
      */
-    private _handleConnectionChange;
+    xp: TimebackUserXp;
+}
+/**
+ * Options for querying student XP.
+ */
+interface GetXpOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse', 'today' */
+    include?: ('perCourse' | 'today')[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
+/**
+ * XP data for a single course.
+ */
+interface CourseXp {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from XP query.
+ */
+interface XpResponse {
+    totalXp: number;
+    todayXp?: number;
+    courses?: CourseXp[];
+}
+
+/**
+ * Core client configuration and lifecycle types
+ */
+
+type TokenType = 'session' | 'apiKey' | 'gameJwt';
+/**
+ * Runtime mode for a Playcademy game client.
+ *
+ * - `'platform'` — game is embedded in the platform (e.g. the cademy hub)
+ *   with a real authenticated user and full access to SDK namespaces.
+ * - `'demo'` — game is embedded in the landing page demo shell with an
+ *   anonymous user; platform-only namespaces throw, and `client.demo.*`
+ *   is the supported surface for signaling demo lifecycle events and
+ *   reading/updating the anonymous profile.
+ * - `'standalone'` — game is running outside any iframe (e.g. `bun run dev`
+ *   or direct-deploy preview) with a mock token and no real platform
+ *   context. API calls will not succeed; use this to branch UX locally.
+ */
+type PlaycademyMode = 'platform' | 'demo' | 'standalone';
+interface ClientConfig {
+    baseUrl: string;
+    gameUrl?: string;
+    token?: string;
+    tokenType?: TokenType;
+    gameId?: string;
+    launchId?: string;
+    autoStartSession?: boolean;
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+    mode?: PlaycademyMode;
+}
+/**
+ * Handler called when connection state changes to offline or degraded.
+ * Games can implement this to handle disconnects gracefully.
+ */
+type DisconnectHandler = (context: DisconnectContext) => void | Promise<void>;
+/**
+ * Context provided to disconnect handlers
+ */
+interface DisconnectContext {
+    /** Current connection state */
+    state: 'offline' | 'degraded';
+    /** Reason for the disconnect */
+    reason: string;
+    /** Timestamp when disconnect was detected */
+    timestamp: number;
+    /** Utility to display a platform-level alert */
+    displayAlert: (message: string, options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    }) => void;
+}
+interface InitPayload {
+    /** Hub API base URL */
+    baseUrl: string;
+    /** Game deployment URL (serves both frontend assets and backend API) */
+    gameUrl?: string;
+    /** Short-lived game token */
+    token: string;
+    /** Game ID */
+    gameId: string;
+    /** Realtime WebSocket URL */
+    realtimeUrl?: string;
+    /** Timeback context (if user has a Timeback account) */
+    timeback?: TimebackInitContext;
+    /** Runtime mode for the game client */
+    mode?: PlaycademyMode;
+}
+interface GameContextPayload {
+    token: string;
+    baseUrl: string;
+    realtimeUrl: string;
+    gameId: string;
+    forwardKeys?: string[];
+    mode?: PlaycademyMode;
+}
+type EventListeners = {
+    [E in keyof ClientEvents]?: ((payload: ClientEvents[E]) => void)[];
+};
+interface ClientEvents {
+    authChange: {
+        token: string | null;
+    };
+    inventoryChange: {
+        itemId: string;
+        delta: number;
+        newTotal: number;
+    };
+    levelUp: {
+        oldLevel: number;
+        newLevel: number;
+        creditsAwarded: number;
+    };
+    xpGained: {
+        amount: number;
+        totalXP: number;
+        leveledUp: boolean;
+    };
+    connectionChange: {
+        state: 'online' | 'offline' | 'degraded';
+        reason: string;
+    };
+}
+
+/**
+ * Event and message payload types for SDK messaging system
+ */
+
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Authentication state change event payload.
+ * Used when authentication state changes in the application.
+ */
+interface AuthStateChangePayload {
+    /** Whether the user is currently authenticated */
+    authenticated: boolean;
+    /** User information if authenticated, null otherwise */
+    user: UserInfo | null;
+    /** Error information if authentication failed */
+    error: Error | null;
+}
+/**
+ * OAuth callback event payload.
+ * Used when OAuth flow completes in popup/new-tab windows.
+ */
+interface AuthCallbackPayload {
+    /** OAuth authorization code */
+    code: string;
+    /** OAuth state parameter for CSRF protection */
+    state: string;
+    /** Error message if OAuth flow failed */
+    error: string | null;
+}
+/**
+ * Token refresh event payload.
+ * Sent when authentication token is updated.
+ */
+interface TokenRefreshPayload {
+    /** New authentication token */
+    token: string;
+    /** Token expiration timestamp */
+    exp: number;
 }
-
 /**
- * @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
+ * Telemetry event payload.
+ * Performance metrics sent from the game.
+ */
+interface TelemetryPayload {
+    /** Frames per second */
+    fps: number;
+    /** Memory usage in MB */
+    mem: number;
+}
+/**
+ * Keyboard event payload.
+ * Key events forwarded from the game.
+ */
+interface KeyEventPayload {
+    /** Key value (e.g., 'Escape', 'F1') */
+    key: string;
+    /** Key code (optional) */
+    code?: string;
+    /** Event type */
+    type: 'keydown' | 'keyup';
+}
+/**
+ * Connection state payload.
+ * Broadcast from platform to games when connection changes.
+ */
+interface ConnectionStatePayload {
+    state: 'online' | 'offline' | 'degraded';
+    reason: string;
+}
+/**
+ * Options for `client.demo.end(score, options?)`.
  *
- * The system automatically detects the runtime environment and chooses the appropriate
- * transport method, abstracting this complexity from the developer.
+ * All optional. The landing-page demo shell can render a meaningful CTA
+ * from `score` alone, but `durationMs` enables a nicer summary and
+ * `metadata` lets games pass any extra context they want to surface.
+ */
+interface DemoEndOptions {
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Wire payload for the `PLAYCADEMY_DEMO_END` message.
  *
- * **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
+ * `score` is required — the demo shell always needs something to display
+ * when the round ends. `durationMs` and `metadata` are optional.
  */
+interface DemoEndPayload extends DemoEndOptions {
+    score: number;
+}
 
 /**
- * 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.)
+ * SDK-specific API response types
  */
-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",
-    /**
-     * Broadcasts connection state changes to games.
-     * Sent by platform when network connectivity changes.
-     * Payload:
-     * - `state`: 'online' | 'offline' | 'degraded'
-     * - `reason`: string
-     */
-    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
-    /**
-     * 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",
-    /**
-     * Game reports key events to parent.
-     * Sent when certain keys are pressed within the game iframe.
-     * Payload:
-     * - `key`: string
-     * - `code?`: string
-     * - `type`: 'keydown' | 'keyup'
-     */
-    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
-    /**
-     * Game requests platform to display an alert.
-     * Sent when connection issues are detected or other important events occur.
-     * Payload:
-     * - `message`: string
-     * - `options`: `{ type?: 'info' | 'warning' | 'error', duration?: number }`
-     */
-    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
-    /**
-     * Notifies about authentication state changes.
-     * Can be sent in both directions depending on auth flow.
-     * Payload:
-     * - `authenticated`: boolean
-     * - `user`: UserInfo | null
-     * - `error`: Error | null
-     */
-    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
+interface LoginResponse {
+    token: string;
+}
+interface GameTokenResponse {
+    token: string;
+    exp: number;
+}
+interface InventoryMutationResponse {
+    newTotal: number;
+}
+
+/**
+ * Realtime namespace types
+ */
+/**
+ * Response type for the realtime token API
+ */
+interface RealtimeTokenResponse {
+    token: string;
+}
+
+/**
+ * Scores namespace types
+ */
+interface ScoreSubmission {
+    id: string;
+    score: number;
+    achievedAt: Date;
+}
+
+/**
+ * Authentication namespace types
+ */
+
+type AuthProviderType = (typeof AUTH_PROVIDER_IDS)[keyof typeof AUTH_PROVIDER_IDS];
+interface AuthOptions {
+    /** The identity provider to use for authentication */
+    provider: AuthProviderType;
+    /** The OAuth callback URL where your server handles the callback */
+    callbackUrl: string;
+    /** Authentication mode - auto detects best option based on context */
+    mode?: 'auto' | 'popup' | 'redirect';
+    /** Callback for authentication state changes */
+    onStateChange?: (state: AuthStateUpdate) => void;
+    /** Custom OAuth configuration (for users embedding the SDK outside of the Playcademy platform) */
+    oauth?: {
+        clientId: string;
+        authorizationEndpoint?: string;
+        tokenEndpoint?: string;
+        scope?: string;
+    };
     /**
-     * OAuth callback data from popup/new-tab windows.
-     * Sent from popup window back to parent after OAuth completes.
-     * Payload:
-     * - `code`: string (OAuth authorization code)
-     * - `state`: string (OAuth state for CSRF protection)
-     * - `error`: string | null (OAuth error if any)
+     * Optional custom data to encode in OAuth state parameter.
+     * By default, the SDK automatically includes playcademy_user_id and game_id.
+     * Use this to add additional custom data if needed.
      */
-    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
+    stateData?: Record<string, string>;
+}
+interface AuthStateUpdate {
+    /** Current status of the authentication flow */
+    status: 'opening_popup' | 'exchanging_token' | 'complete' | 'error';
+    /** Human-readable message about the current state */
+    message: string;
+    /** Error details if status is 'error' */
+    error?: Error;
+}
+interface AuthResult {
+    /** Whether authentication was successful */
+    success: boolean;
+    /** User information if authentication was successful */
+    user?: UserInfo;
+    /** Error if authentication failed */
+    error?: Error;
+}
+
+type DevUploadEvent = {
+    type: 'init';
+} | {
+    type: 's3Progress';
+    loaded: number;
+    total: number;
+    percent: number;
+} | {
+    type: 'finalizeStart';
+} | {
+    type: 'finalizeProgress';
+    percent: number;
+    currentFileLabel?: string;
+} | {
+    type: 'finalizeStatus';
+    message: string;
+} | {
+    type: 'complete';
+} | {
+    type: 'close';
+};
+interface DevUploadHooks {
+    onEvent?: (e: DevUploadEvent) => void;
+    onClose?: () => void;
 }
+
 /**
- * Type definition for message handler functions.
- * These functions are called when a specific message type is received.
+ * Connection Manager
  *
- * @template T - The type of payload data the handler expects
- * @param payload - The data sent with the message
+ * Manages connection monitoring and integrates it with the Playcademy client.
+ * Handles event wiring, state management, and disconnect callbacks.
+ *
+ * In iframe mode, disables local monitoring and listens to platform connection
+ * state broadcasts instead (avoids duplicate heartbeats).
  */
-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)}`)
- * })
- * ```
+ * Configuration for the ConnectionManager.
  */
-interface 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]: TokenRefreshPayload;
-    /** 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;
-    /** Connection state change from platform */
-    [MessageEvents.CONNECTION_STATE]: ConnectionStatePayload;
-    /** Ready message has no payload data */
-    [MessageEvents.READY]: void;
-    /** Exit message has no payload data */
-    [MessageEvents.EXIT]: void;
-    /** Performance telemetry data */
-    [MessageEvents.TELEMETRY]: TelemetryPayload;
-    /** Key event data */
-    [MessageEvents.KEY_EVENT]: KeyEventPayload;
-    /** Display alert request from game */
-    [MessageEvents.DISPLAY_ALERT]: DisplayAlertPayload;
-    /** Authentication state change notification */
-    [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
-    /** OAuth callback data from popup/new-tab windows */
-    [MessageEvents.AUTH_CALLBACK]: AuthCallbackPayload;
+interface ConnectionManagerConfig {
+    /** Base URL for API requests (used for heartbeat pings) */
+    baseUrl: string;
+    /** Authentication context (iframe vs standalone) for alert routing */
+    authContext?: {
+        isInIframe: boolean;
+    };
+    /** Handler to call when connection issues are detected */
+    onDisconnect?: DisconnectHandler;
+    /** Callback to emit connection change events to the client */
+    onConnectionChange?: (state: ConnectionState, reason: string) => void;
 }
 /**
- * **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
+ * Manages connection monitoring for the Playcademy client.
  *
- * **Example Usage**:
- * ```typescript
- * // Send a message (automatically chooses transport)
- * messaging.send(MessageEvents.READY, undefined)
+ * The ConnectionManager serves as an integration layer between the low-level
+ * ConnectionMonitor and the PlaycademyClient. It handles:
+ * - Event wiring and coordination
+ * - Disconnect callbacks with context
+ * - Platform-level alert integration
+ * - Request success/failure tracking
  *
- * // Listen for messages (handles both transports)
- * messaging.listen(MessageEvents.INIT, (payload) => {
- *   console.log('Game initialized with:', payload)
- * })
+ * This class is used internally by PlaycademyClient and typically not
+ * instantiated directly by game developers.
  *
- * // Clean up listeners
- * messaging.unlisten(MessageEvents.INIT, handler)
- * ```
+ * @see {@link ConnectionMonitor} for the underlying monitoring implementation
+ * @see {@link PlaycademyClient.onDisconnect} for the public API
  */
-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, OR when target window is specified
-     * - **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)
-     * @param options - Optional configuration for message sending
-     *
-     * @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 })
-     *
-     * // Send to specific iframe window (parent to iframe communication)
-     * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId }, {
-     *   target: iframe.contentWindow,
-     *   origin: '*'
-     * })
-     *
-     * // 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?: {
-        target?: Window;
-        origin?: string;
-    }): 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;
+declare class ConnectionManager {
+    private monitor?;
+    private authContext?;
+    private disconnectHandler?;
+    private connectionChangeCallback?;
+    private currentState;
+    private additionalDisconnectHandlers;
     /**
-     * **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.
+     * Creates a new ConnectionManager instance.
      *
-     * @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()
+     * @param config - Configuration options for the manager
      *
      * @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
+     * const manager = new ConnectionManager({
+     *   baseUrl: 'https://api.playcademy.com',
+     *   authContext: { isInIframe: false },
+     *   onDisconnect: (context) => {
+     *     console.log(`Disconnected: ${context.state}`)
+     *   },
+     *   onConnectionChange: (state, reason) => {
+     *     console.log(`Connection changed: ${state}`)
+     *   }
+     * })
      * ```
      */
-    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    constructor(config: ConnectionManagerConfig);
     /**
-     * **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, or postMessage with target)
-     *
-     * **Cross-Context Communication**:
-     * 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, 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
-     * configurable for production security.
+     * Gets the current connection state.
      *
-     * @param eventType - The message event type being sent
-     * @returns Configuration object with transport method and target information
+     * @returns The current connection state ('online', 'offline', or 'degraded')
      *
      * @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: '*' }
+     * const state = manager.getState()
+     * if (state === 'offline') {
+     *   console.log('No connection')
+     * }
      * ```
      */
-    private getMessagingContext;
+    getState(): ConnectionState;
     /**
-     * **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`: The message data (if any)
+     * Manually triggers a connection check immediately.
      *
-     * **Payload Handling**:
-     * - **All payloads**: Wrapped in a `payload` property for consistency (e.g., { type, payload: data })
-     * - **Undefined payloads**: Only the type is sent (e.g., { type })
+     * Forces a heartbeat ping to verify the current connection status.
+     * Useful when you need to check connectivity before a critical operation.
      *
-     * **Security**:
-     * The origin parameter controls which domains can receive the message.
-     * Currently set to '*' for development, but should be restricted in production.
+     * In iframe mode, this returns the last known state from platform.
      *
-     * @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 '*')
+     * @returns Promise resolving to the current connection state
      *
      * @example
      * ```typescript
-     * // Send ready signal (no payload)
-     * sendViaPostMessage(MessageEvents.READY, undefined)
-     * // Sends: { type: 'PLAYCADEMY_READY' }
+     * const state = await manager.checkNow()
+     * if (state === 'online') {
+     *   await performCriticalOperation()
+     * }
+     * ```
+     */
+    checkNow(): Promise<ConnectionState>;
+    /**
+     * Reports a successful API request to the connection monitor.
      *
-     * // Send telemetry data (object payload)
-     * sendViaPostMessage(MessageEvents.TELEMETRY, { fps: 60, mem: 128 })
-     * // Sends: { type: 'PLAYCADEMY_TELEMETRY', payload: { fps: 60, mem: 128 } }
+     * This resets the consecutive failure counter and transitions from
+     * 'degraded' to 'online' state if applicable.
      *
-     * // Send overlay state (primitive payload)
-     * sendViaPostMessage(MessageEvents.OVERLAY, true)
-     * // Sends: { type: 'PLAYCADEMY_OVERLAY', payload: true }
-     * ```
+     * Typically called automatically by the SDK's request wrapper.
+     * No-op in iframe mode (platform handles monitoring).
      */
-    private sendViaPostMessage;
+    reportRequestSuccess(): void;
     /**
-     * **Send Via CustomEvent Method**
+     * Reports a failed API request to the connection monitor.
      *
-     * 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.
+     * Only network errors are tracked (not 4xx/5xx HTTP responses).
+     * After consecutive failures exceed the threshold, the state transitions
+     * to 'degraded' or 'offline'.
      *
-     * **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.
+     * Typically called automatically by the SDK's request wrapper.
+     * No-op in iframe mode (platform handles monitoring).
      *
-     * **Event Structure**:
-     * - **type**: The event name (e.g., 'PLAYCADEMY_INIT')
-     * - **detail**: The payload data attached to the event
+     * @param error - The error from the failed request
+     */
+    reportRequestFailure(error: unknown): void;
+    /**
+     * Registers a callback to be called when connection issues are detected.
      *
-     * **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
+     * The callback only fires for 'offline' and 'degraded' states, not when
+     * recovering to 'online'. This provides a clean API for games to handle
+     * disconnect scenarios without being notified of every state change.
      *
-     * **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)`.
+     * Works in both iframe and standalone modes transparently.
      *
-     * @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)
+     * @param callback - Function to call when connection degrades
+     * @returns Cleanup function to unregister the callback
      *
      * @example
      * ```typescript
-     * // Send initialization data
-     * sendViaCustomEvent(MessageEvents.INIT, {
-     *   baseUrl: '/api',
-     *   token: 'abc123',
-     *   gameId: 'game-456'
+     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
+     *   if (state === 'offline') {
+     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
+     *     saveGameState()
+     *   }
      * })
-     * // 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'
-     * })
+     * // Later: cleanup() to unregister
      * ```
      */
-    private sendViaCustomEvent;
+    onDisconnect(callback: DisconnectHandler): () => void;
+    /**
+     * Stops connection monitoring and performs cleanup.
+     *
+     * Removes event listeners and clears heartbeat intervals.
+     * Should be called when the client is being destroyed.
+     */
+    stop(): void;
+    /**
+     * Sets up listener for platform connection state broadcasts (iframe mode only).
+     */
+    private _setupPlatformListener;
+    /**
+     * Handles connection state changes from the monitor or platform.
+     *
+     * Coordinates between:
+     * 1. Emitting events to the client (for client.on('connectionChange'))
+     * 2. Calling the disconnect handler if configured
+     * 3. Calling any additional handlers registered via onDisconnect()
+     *
+     * @param state - The new connection state
+     * @param reason - Human-readable reason for the state change
+     */
+    private _handleConnectionChange;
 }
-/**
- * **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.
- */
-declare const messaging: PlaycademyMessaging;
 
 export { ApiError, ConnectionManager, ConnectionMonitor, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody };
+export type { ApiErrorCode, ApiErrorInfo, ConnectionMonitorConfig, ConnectionState, ConnectionStatePayload, DevUploadEvent, DevUploadHooks, DisconnectContext, DisconnectHandler, DisplayAlertPayload, ErrorResponseBody, PlaycademyMode };