@playcademy/sdk 0.1.13 → 0.1.15

package/dist/types.d.ts

@@ -226,6 +226,23 @@ type GameMetadata = {
     emoji?: string;
     [key: string]: unknown;
 };
+/**
+ * DNS validation records for custom hostname
+ * Structure for the validationRecords JSON field in game_custom_hostnames table
+ */
+type CustomHostnameValidationRecords = {
+    /** TXT record for ownership verification */
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    /** TXT records for SSL certificate validation */
+    ssl?: Array<{
+        txt_name?: string;
+        txt_value?: string;
+    }>;
+};
 declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "games";
     schema: undefined;
@@ -338,8 +355,8 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        assetBundleBase: drizzle_orm_pg_core.PgColumn<{
-            name: "asset_bundle_base";
+        deploymentUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "deployment_url";
             tableName: "games";
             dataType: "string";
             columnType: "PgText";
@@ -554,6 +571,207 @@ declare const gameSessions: drizzle_orm_pg_core.PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
+/**
+ * Custom hostnames table
+ *
+ * Stores custom domain mappings for games with SSL provisioning via Cloudflare.
+ */
+declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "game_custom_hostnames";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        gameId: drizzle_orm_pg_core.PgColumn<{
+            name: "game_id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: drizzle_orm_pg_core.PgColumn<{
+            name: "user_id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        hostname: drizzle_orm_pg_core.PgColumn<{
+            name: "hostname";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        cloudflareId: drizzle_orm_pg_core.PgColumn<{
+            name: "cloudflare_id";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        environment: drizzle_orm_pg_core.PgColumn<{
+            name: "environment";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "staging" | "production";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["staging", "production"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: drizzle_orm_pg_core.PgColumn<{
+            name: "status";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "pending" | "pending_validation" | "pending_deployment" | "pending_deletion" | "active" | "blocked" | "deleted";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "pending_validation", "pending_deployment", "pending_deletion", "active", "blocked", "deleted"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sslStatus: drizzle_orm_pg_core.PgColumn<{
+            name: "ssl_status";
+            tableName: "game_custom_hostnames";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "pending_validation" | "pending_deployment" | "active" | "deleted" | "initializing" | "pending_issuance";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["initializing", "pending_validation", "pending_issuance", "pending_deployment", "active", "deleted"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        validationRecords: drizzle_orm_pg_core.PgColumn<{
+            name: "validation_records";
+            tableName: "game_custom_hostnames";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: CustomHostnameValidationRecords;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: CustomHostnameValidationRecords;
+        }>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "game_custom_hostnames";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "game_custom_hostnames";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
     schema: undefined;
@@ -648,7 +866,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "items";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1892,7 +2110,7 @@ declare const characterComponents: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "character_components";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "body" | "outfit" | "hairstyle" | "eyes" | "accessory";
+            data: "accessory" | "body" | "outfit" | "hairstyle" | "eyes";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -2959,66 +3177,32 @@ declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
     mapElementId?: string | null | undefined;
     metadata?: Record<string, unknown> | undefined;
 }>;
+/**
+ * Simplified game manifest for Cloudflare Workers deployments
+ *
+ * The manifest is auto-generated by build tools (Godot plugin, Vite plugin, etc.)
+ * and provides minimal metadata about the build.
+ *
+ * Fields:
+ * - version: Manifest schema version (for future migrations)
+ * - platform: Auto-detected by build tool (e.g., 'web', 'godot@4.3', 'unity@2023')
+ * - createdAt: Build timestamp (ISO 8601)
+ *
+ * Note: With unified Cloudflare Workers deployments, the worker handles all routing
+ * internally, so we no longer need bootMode, entryPoint, or styles fields.
+ */
 declare const ManifestV1Schema: z.ZodObject<{
     version: z.ZodString;
-    bootMode: z.ZodEnum<["iframe", "module"]>;
-    entryPoint: z.ZodEffects<z.ZodString, string, string>;
-    /**
-     * An array of relative paths to CSS stylesheets.
-     * Currently, this property is ONLY utilized by the 'module' boot mode
-     * (`apps/cademy/src/lib/loader/boot-module.ts`) to load external
-     * stylesheets into the game's shadow DOM.
-     *
-     * This property is under review for potential deprecation and removal.
-     * The 'module' boot mode itself has not yet seen significant adoption
-     * or clear use-cases, and if support for module loading is removed in
-     * the future, this 'styles' property would become obsolete.
-     *
-     * If module-based games need styling, alternative approaches might involve
-     * bundling CSS within their JavaScript or managing style injection internally.
-     */
-    styles: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, string[] | undefined>;
-    /**
-     * Specifies the game or development platform.
-     * Current values include 'web', 'godot', and 'unity'.
-     * The default in the database is 'web'.
-     *
-     * IMPORTANT: This property is NOT CURRENTLY USED by the core loader
-     * or runtime systems in any functional way. It is present in the manifest
-     * but does not drive any specific behavior in `boot-iframe.ts` or
-     * `boot-module.ts` beyond being a piece of metadata.
-     *
-     * Potential Future Uses (Speculative):
-     * - Analytics: Could be used to gather stats on platform popularity/usage.
-     * - Developer Portal: Might inform UI/UX in the dev portal, e.g., showing
-     *   platform-specific guides or settings.
-     * - Loader Optimizations: In the future, the loader could potentially use this
-     *   to apply platform-specific loading strategies or workarounds, though this
-     *   is unlikely given the current generic boot process.
-     * - Asset Pipeline: Could hint to future asset pipeline tools about expected
-     *   project structures or build artifacts for different platforms.
-     *
-     * The field is intentionally kept somewhat generic. If finer-grained
-     * distinctions are ever needed (e.g., specific web frameworks like 'phaser',
-     * 'three'), this schema might need to be revisited or a separate
-     * 'platformVersion' or 'framework' field could be added.
-     */
-    platform: z.ZodEnum<["web", "godot", "unity"]>;
+    platform: z.ZodString;
     createdAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     createdAt: string;
     version: string;
-    platform: "web" | "godot" | "unity";
-    bootMode: "iframe" | "module";
-    entryPoint: string;
-    styles?: string[] | undefined;
+    platform: string;
 }, {
     createdAt: string;
     version: string;
-    platform: "web" | "godot" | "unity";
-    bootMode: "iframe" | "module";
-    entryPoint: string;
-    styles?: string[] | undefined;
+    platform: string;
 }>;
 declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
     id: drizzle_orm_pg_core.PgColumn<{
@@ -3111,7 +3295,7 @@ declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
         tableName: "items";
         dataType: "string";
         columnType: "PgEnumColumn";
-        data: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+        data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
         driverParam: string;
         notNull: true;
         hasDefault: true;
@@ -3207,21 +3391,21 @@ declare const UpdateItemSchema: z.ZodObject<Omit<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     createdAt: z.ZodOptional<z.ZodDate>;
 }, "id" | "createdAt">, "strip", z.ZodTypeAny, {
+    slug?: string | undefined;
     description?: string | null | undefined;
     displayName?: string | undefined;
-    slug?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     gameId?: string | null | undefined;
-    type?: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other" | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
 }, {
+    slug?: string | undefined;
     description?: string | null | undefined;
     displayName?: string | undefined;
-    slug?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     gameId?: string | null | undefined;
-    type?: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other" | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
 }>;
@@ -3267,10 +3451,10 @@ declare const InsertShopListingSchema: z.ZodObject<Omit<{
     createdAt: z.ZodOptional<z.ZodDate>;
     updatedAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
 }, "id" | "createdAt" | "updatedAt">, "strip", z.ZodTypeAny, {
+    isActive: boolean;
     itemId: string;
     currencyId: string;
     price: number;
-    isActive: boolean;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
     availableFrom?: Date | null | undefined;
@@ -3279,37 +3463,37 @@ declare const InsertShopListingSchema: z.ZodObject<Omit<{
     itemId: string;
     currencyId: string;
     price: number;
+    isActive?: boolean | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }>;
 declare const UpdateShopListingSchema: z.ZodObject<{
+    isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     itemId: z.ZodOptional<z.ZodString>;
     currencyId: z.ZodOptional<z.ZodString>;
     price: z.ZodOptional<z.ZodNumber>;
     sellBackPercentage: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodNumber>>>;
     stock: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodNumber>>>;
-    isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     availableFrom: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
     availableUntil: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
 }, "strip", z.ZodTypeAny, {
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }, {
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
 }>;
@@ -3397,32 +3581,22 @@ type PlayerCharacter = typeof playerCharacters.$inferSelect & {
 };
 type PlayerCharacterAccessory = typeof playerCharacterAccessories.$inferSelect;
 type GameRow = typeof games.$inferSelect;
-type BaseGame = Omit<GameRow, 'gameType' | 'assetBundleBase' | 'externalUrl'>;
+type BaseGame = Omit<GameRow, 'gameType' | 'deploymentUrl' | 'externalUrl'>;
 type HostedGame = BaseGame & {
     gameType: 'hosted';
-    assetBundleBase: string;
+    deploymentUrl: string;
     externalUrl: null;
 };
 type ExternalGame = BaseGame & {
     gameType: 'external';
-    assetBundleBase: null;
+    deploymentUrl: null;
     externalUrl: string;
 };
 type Game = HostedGame | ExternalGame;
 type GameSession = typeof gameSessions.$inferSelect;
 type GameStateData = Record<string, unknown>;
+type GameCustomHostname = typeof gameCustomHostnames.$inferSelect;
 type UpsertGameMetadataInput = z.infer<typeof UpsertGameMetadataSchema>;
-/**
- * Response from backend deployment API
- */
-interface BackendDeploymentResponse {
-    /** Unique deployment ID */
-    deploymentId: string;
-    /** Backend API URL */
-    url: string;
-    /** Deployment timestamp */
-    deployedAt: string;
-}
 type Item = typeof items.$inferSelect;
 type InventoryItem = typeof inventoryItems.$inferSelect;
 type Currency = typeof currencies.$inferSelect;
@@ -3509,10 +3683,12 @@ type CharacterComponentWithSpriteUrl = CharacterComponent & {
 type InventoryItemWithItem = Omit<InventoryItem, 'itemId'> & {
     item: Item;
 };
-type HostedGameWithManifest = HostedGame & {
-    manifest: ManifestV1;
+/**
+ * Game with optional manifest metadata from build tools
+ */
+type FetchedGame = (HostedGame | ExternalGame | GameRow) & {
+    manifest?: ManifestV1;
 };
-type FetchedGame = HostedGameWithManifest | GameRow;
 /**
  * Map-related Composite Types
  * Types that combine map, game, and item data for rendering and interaction
@@ -3933,6 +4109,8 @@ interface IntegrationsConfig {
     kv?: boolean;
     /** Bucket storage (optional) */
     bucket?: boolean;
+    /** Authentication (optional) */
+    auth?: boolean;
 }
 /**
  * Unified Playcademy configuration
@@ -4066,6 +4244,20 @@ interface UserScore {
     gameSlug: string;
 }
 
+/**
+ * Connection monitoring types
+ *
+ * Type definitions for connection state, configuration, and callbacks.
+ */
+/**
+ * Possible connection states.
+ *
+ * - **online**: Connection is stable and healthy
+ * - **offline**: Complete loss of network connectivity
+ * - **degraded**: Connection is slow or experiencing intermittent issues
+ */
+type ConnectionState = 'online' | 'offline' | 'degraded';
+
 /**
  * @fileoverview Playcademy Messaging System
  *
@@ -4147,6 +4339,14 @@ declare enum MessageEvents {
      * 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.
@@ -4176,6 +4376,14 @@ declare enum MessageEvents {
      * - `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.
@@ -4223,6 +4431,8 @@ declare enum MessageEvents {
 declare function init(options?: {
     baseUrl?: string;
     allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
 }): Promise<PlaycademyClient>;
 
 /**
@@ -4276,6 +4486,7 @@ declare class PlaycademyClient {
     private internalClientSessionId?;
     private authContext?;
     private initPayload?;
+    private connectionManager?;
     /**
      * Creates a new PlaycademyClient instance.
      *
@@ -4367,6 +4578,85 @@ declare class PlaycademyClient {
      * @param callback - Function to call when auth state changes
      */
     onAuthChange(callback: (token: string | null) => void): void;
+    /**
+     * Registers a callback to be called when connection issues are detected.
+     *
+     * This is a convenience method that filters connection change events to only
+     * fire when the connection degrades (offline or degraded states). Use this
+     * when you want to handle disconnects without being notified of recoveries.
+     *
+     * For all connection state changes, use `client.on('connectionChange', ...)` instead.
+     *
+     * @param callback - Function to call when connection state changes to offline or degraded
+     * @returns Cleanup function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
+     *   console.log(`Connection ${state}: ${reason}`)
+     *
+     *   if (state === 'offline') {
+     *     // Save state and return to game lobby
+     *     displayAlert?.('Connection lost. Your progress has been saved.', { type: 'error' })
+     *     saveGameState()
+     *     returnToLobby()
+     *   } else if (state === 'degraded') {
+     *     displayAlert?.('Slow connection detected.', { type: 'warning' })
+     *   }
+     * })
+     *
+     * // Later: cleanup() to unregister
+     * ```
+     *
+     * @see {@link DISCONNECT_HANDLING.md} for detailed usage examples
+     * @see {@link ConnectionManager.onDisconnect} for the underlying implementation
+     */
+    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    /**
+     * Gets the current connection state.
+     *
+     * Returns the last known connection state without triggering a new check.
+     * Use `checkConnection()` to force an immediate verification.
+     *
+     * @returns Current connection state ('online', 'offline', 'degraded') or 'unknown' if monitoring is disabled
+     *
+     * @example
+     * ```typescript
+     * const state = client.getConnectionState()
+     * if (state === 'offline') {
+     *   console.log('No connection available')
+     * }
+     * ```
+     *
+     * @see {@link checkConnection} to trigger an immediate connection check
+     * @see {@link ConnectionManager.getState} for the underlying implementation
+     */
+    getConnectionState(): ConnectionState | 'unknown';
+    /**
+     * Manually triggers a connection check immediately.
+     *
+     * Forces a heartbeat ping to verify connectivity right now, bypassing the normal
+     * interval. Useful when you need to verify connection status before a critical
+     * operation (e.g., saving important game state).
+     *
+     * @returns Promise resolving to the current connection state after verification
+     *
+     * @example
+     * ```typescript
+     * // Check before critical operation
+     * const state = await client.checkConnection()
+     * if (state !== 'online') {
+     *   alert('Please check your internet connection before saving')
+     *   return
+     * }
+     *
+     * await client.games.saveState(importantData)
+     * ```
+     *
+     * @see {@link getConnectionState} to get the last known state without checking
+     * @see {@link ConnectionManager.checkNow} for the underlying implementation
+     */
+    checkConnection(): Promise<ConnectionState | 'unknown'>;
     /**
      * Sets the authentication context for the client.
      * This is called during initialization to store environment info.
@@ -4429,6 +4719,11 @@ declare class PlaycademyClient {
      * Safe to call in any environment - isInIframe handles browser detection.
      */
     private _detectAuthContext;
+    /**
+     * Initializes connection monitoring if enabled.
+     * Safe to call in any environment - only runs in browser.
+     */
+    private _initializeConnectionMonitor;
     /**
      * Initializes an internal game session for automatic session management.
      * Only starts a session if:
@@ -4552,15 +4847,17 @@ declare class PlaycademyClient {
             get: () => Promise<DeveloperStatusValue>;
         };
         games: {
-            deploy: {
-                frontend: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob | null, hooks?: DevUploadHooks) => Promise<Game>;
-                backend: (slug: string, bundle: BackendDeploymentBundle) => Promise<BackendDeploymentResponse>;
-                seed: (slug: string, code: string, environment?: "staging" | "production") => Promise<{
-                    success: boolean;
-                    deploymentId: string;
-                    executedAt: string;
-                }>;
-            };
+            deploy: (slug: string, options: {
+                metadata?: UpsertGameMetadataInput;
+                file?: File | Blob | null;
+                backend?: BackendDeploymentBundle;
+                hooks?: DevUploadHooks;
+            }) => Promise<Game>;
+            seed: (slug: string, code: string, environment?: "staging" | "production") => Promise<{
+                success: boolean;
+                deploymentId: string;
+                executedAt: string;
+            }>;
             upsert: (slug: string, metadata: UpsertGameMetadataInput) => Promise<Game>;
             delete: (gameId: string) => Promise<void>;
             secrets: {
@@ -4586,6 +4883,12 @@ declare class PlaycademyClient {
                 put: (slug: string, key: string, content: Blob | ArrayBuffer | Uint8Array, contentType?: string) => Promise<void>;
                 delete: (slug: string, key: string) => Promise<void>;
             };
+            domains: {
+                add: (slug: string, hostname: string) => Promise<GameCustomHostname>;
+                list: (slug: string) => Promise<GameCustomHostname[]>;
+                status: (slug: string, hostname: string, refresh?: boolean) => Promise<GameCustomHostname>;
+                delete: (slug: string, hostname: string) => Promise<void>;
+            };
         };
         items: {
             create: (gameId: string, slug: string, itemData: Omit<InsertItemInput, "slug" | "gameId">) => Promise<Item>;
@@ -4622,50 +4925,50 @@ declare class PlaycademyClient {
         };
         items: {
             create: (props: InsertItemInput) => Promise<{
-                metadata: unknown;
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             get: (itemId: string) => Promise<{
-                metadata: unknown;
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             list: () => Promise<{
-                metadata: unknown;
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }[]>;
             update: (itemId: string, props: UpdateItemInput) => Promise<{
-                metadata: unknown;
-                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
-                slug: string;
                 id: string;
                 createdAt: Date;
                 gameId: string | null;
+                slug: string;
                 displayName: string;
+                metadata: unknown;
                 description: string | null;
+                type: "accessory" | "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
                 isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
@@ -4800,9 +5103,7 @@ declare class PlaycademyClient {
             }) => Promise<TodayXpResponse>;
             total: () => Promise<TotalXpResponse>;
             history: (options?: {
-                startDate
-                /** Auto-initializes a PlaycademyClient with context from the environment */
-                ?: string;
+                startDate?: string;
                 endDate?: string;
             }) => Promise<XpHistoryResponse>;
             summary: (options?: {
@@ -4923,14 +5224,41 @@ interface ClientConfig {
     tokenType?: TokenType;
     gameId?: 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;
-    cdnBase?: string;
 }
 type AuthProviderType = (typeof AUTH_PROVIDER_IDS)[keyof typeof AUTH_PROVIDER_IDS];
 interface AuthOptions {
@@ -5064,6 +5392,32 @@ interface KeyEventPayload {
     /** Event type */
     type: 'keydown' | 'keyup';
 }
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Display alert payload.
+ * Request from game to show platform-level alert.
+ */
+interface DisplayAlertPayload {
+    message: string;
+    options?: {
+        type?: 'info' | 'warning' | 'error';
+        duration?: number;
+    };
+}
+/**
+ * Connection state payload.
+ * Broadcast from platform to games when connection changes.
+ */
+interface ConnectionStatePayload {
+    state: 'online' | 'offline' | 'degraded';
+    reason: string;
+}
 interface ClientEvents {
     authChange: {
         token: string | null;
@@ -5083,6 +5437,10 @@ interface ClientEvents {
         totalXP: number;
         leveledUp: boolean;
     };
+    connectionChange: {
+        state: 'online' | 'offline' | 'degraded';
+        reason: string;
+    };
 }
 type GameContextPayload = {
     token: string;
@@ -5178,4 +5536,4 @@ interface BucketFile {
 }
 
 export { PlaycademyClient };
-export type { Achievement, AchievementCurrent, AchievementProgressResponse, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, ClientConfig, ClientEvents, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, EventListeners, ExternalGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, HostedGameWithManifest, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, User, UserInfo, UserLevel, UserLevelWithConfig, UserRank, UserRankResponse, UserRoleEnumType, UserScore$1 as UserScore, XpHistoryResponse };
+export type { Achievement, AchievementCurrent, AchievementProgressResponse, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponent, CharacterComponentWithSpriteUrl, ClientConfig, ClientEvents, ConnectionStatePayload, Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusResponse, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameLeaderboardEntry, GameSession, GameStateData, GameTokenResponse, GameUser, HostedGame, InitPayload, InventoryItem, InventoryItemWithItem, InventoryMutationResponse, Item, KeyEventPayload, LeaderboardEntry, LevelConfig, LoginResponse, ManifestV1, Map, MapElement, MapElementWithGame, MapObject, MapObjectWithItem, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacter, ShopCurrency, ShopDisplayItem, ShopViewResponse, SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, User, UserInfo, UserLevel, UserLevelWithConfig, UserRank, UserRankResponse, UserRoleEnumType, UserScore$1 as UserScore, XpHistoryResponse };