@playcademy/sdk 0.4.1-beta.4 → 0.4.1-beta.6

package/dist/internal.d.ts

@@ -9,352 +9,70 @@ import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 
 /**
- * User Types
+ * TimeBack Enums & Literal Types
  *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ * Basic type definitions used throughout the TimeBack integration.
  *
- * @module types/user
+ * @module types/timeback/types
  */
-type UserRoleEnumType = 'admin' | 'player' | 'developer' | 'teacher';
-type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
-type DeveloperStatusValue = DeveloperStatusEnumType;
-type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
-type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-interface UserEnrollment {
-    gameId?: string;
-    courseId: string;
-    grade: number;
-    subject: string;
-    orgId?: string;
-}
-interface UserOrganization {
-    id: string;
-    name: string | null;
-    type: TimebackOrgType | string;
-    isPrimary: boolean;
-}
-interface TimebackStudentProfile {
-    role: TimebackUserRole;
-    organizations: UserOrganization[];
-}
-interface UserTimebackData extends TimebackStudentProfile {
-    id: string;
-    enrollments: UserEnrollment[];
-}
 /**
- * OpenID Connect UserInfo claims (NOT a database row).
+ * Valid TimeBack subject values for course configuration.
+ * These are the supported subject values for OneRoster courses.
  */
-interface UserInfo {
-    sub: string;
-    email: string;
-    name: string | null;
-    email_verified?: boolean;
-    given_name?: string;
-    family_name?: string;
-    issuer?: string;
-    lti_roles?: unknown;
-    lti_context?: unknown;
-    lti_resource_link?: unknown;
-    timeback_id?: string;
-}
-interface DeveloperStatusResponse {
-    status: DeveloperStatusEnumType;
-}
+type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
 /**
- * Authenticated user for API responses.
- * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
  */
-interface AuthenticatedUser {
-    id: string;
-    email: string;
-    emailVerified: boolean;
-    name: string | null;
-    image: string | null;
-    username: string | null;
-    role: UserRoleEnumType;
-    developerStatus: DeveloperStatusEnumType;
-    characterCreated: boolean;
-    createdAt: Date;
-    updatedAt: Date;
-    hasTimebackAccount: boolean;
-    timeback?: UserTimebackData;
-}
-interface GameUser {
-    id: string;
-    name: string | null;
-    role: UserRoleEnumType;
-    username: string | null;
-    email: string | null;
-    timeback?: UserTimebackData;
-}
-
+type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
 /**
- * Game Types
- *
- * Literal types and API DTOs. Database row types are in @playcademy/data/types.
- *
- * @module types/game
+ * Valid Caliper subject values.
+ * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
  */
-type GameType = 'hosted' | 'external';
-type GamePlatform = 'web' | 'godot' | 'unity' | (string & {});
+type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
 /**
- * Game manifest file format (manifest.json).
- * Note: createdAt is a string here because it's parsed from JSON file.
+ * OneRoster organization types.
  */
-interface ManifestV1 {
-    version: string;
-    platform: string;
-    createdAt: string;
-}
-/** Log entry captured from seed worker console output */
-interface SeedLogEntry {
-    /** Log level (log, warn, error, info) */
-    level: 'log' | 'warn' | 'error' | 'info';
-    /** Log message content */
-    message: string;
-    /** Milliseconds since seed execution started */
-    timestamp: number;
-}
-/** Structured error details from D1/SQLite errors */
-interface SeedErrorDetails {
-    /** Error category code */
-    code?: 'CONSTRAINT_VIOLATION' | 'SQL_ERROR' | 'DATABASE_BUSY';
-    /** Table name involved in the error */
-    table?: string;
-    /** Constraint name or column that caused the error */
-    constraint?: string;
-    /** Specific constraint type */
-    constraintType?: 'UNIQUE' | 'FOREIGN_KEY' | 'NOT_NULL';
-    /** Token near syntax error */
-    nearToken?: string;
-    /** Specific error type within category */
-    errorType?: 'TABLE_NOT_FOUND' | 'SYNTAX_ERROR';
-}
+type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
 /**
- * API response for seed operations (what the API returns to the CLI).
- *
- * Extends the worker response with deployment metadata.
+ * Lesson types for PowerPath integration.
  */
-interface SeedResponse {
-    /** Whether the seed completed successfully */
-    success: boolean;
-    /** Unique identifier for the seed worker deployment */
-    deploymentId: string;
-    /** When the seed was executed (ISO 8601 string from JSON serialization) */
-    executedAt: string;
-    /** Captured console output from the seed script */
-    logs?: SeedLogEntry[];
-    /** Execution duration in milliseconds */
-    duration?: number;
-    /** Error message if seed failed */
-    error?: string;
-    /** Stack trace if seed failed */
-    stack?: string;
-    /** Structured error details if seed failed */
-    details?: SeedErrorDetails;
-}
-interface DomainValidationRecords {
-    ownership?: {
-        name?: string;
-        value?: string;
-        type?: string;
-    };
-    ssl?: {
-        txt_name?: string;
-        txt_value?: string;
-    }[];
-}
+type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
 
 /**
- * Leaderboard Types
+ * TimeBack Configuration Types
  *
- * @module types/leaderboard
+ * Configuration interfaces for Organization, Course, Component,
+ * Resource, and complete TimeBack setup.
+ *
+ * @module types/timeback/config
  */
-type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
-interface LeaderboardOptions {
-    timeframe?: LeaderboardTimeframe;
-    limit?: number;
-    offset?: number;
-    gameId?: string;
-}
-interface LeaderboardEntry {
-    rank: number;
-    userId: string;
-    username: string;
-    userImage?: string | null;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId?: string;
-    gameTitle?: string;
-    gameSlug?: string;
-}
-interface UserRank {
-    rank: number;
-    totalPlayers: number;
-    score: number;
-    percentile: number;
-}
-interface UserRankResponse {
-    rank: number;
-    score: number;
-    userId: string;
-}
-interface UserScore {
-    id: string;
-    score: number;
-    achievedAt: Date;
-    metadata?: Record<string, unknown>;
-    gameId: string;
-    gameTitle: string;
-    gameSlug: string;
-}
+
 /**
- * Leaderboard entry with required game context.
- * Used when fetching leaderboards for a specific game.
+ * Organization configuration for TimeBack (user input - optionals allowed)
  */
-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;
+interface OrganizationConfig {
+    /** Display name for your organization */
+    name?: string;
+    /** Organization type */
+    type?: OrganizationType;
+    /** Unique identifier (defaults to Playcademy's org) */
+    identifier?: string;
 }
-
 /**
- * Achievement Types
- *
- * @module types/achievement
+ * Course goals for daily student targets
  */
-type AchievementScopeType = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'game' | 'global' | 'map' | 'level' | 'event';
-declare enum AchievementCompletionType {
-    TIME_PLAYED_SESSION = "time_played_session",
-    INTERACTION = "interaction",
-    LEADERBOARD_RANK = "leaderboard_rank",
-    FIRST_SCORE = "first_score",
-    PERSONAL_BEST = "personal_best"
-}
-interface AchievementCurrent {
-    id: string;
-    title: string;
-    description?: string | null;
-    scope: AchievementScopeType;
-    rewardCredits: number;
-    limit: number;
-    completionType: string;
-    completionConfig: unknown;
-    target: unknown;
-    active: boolean;
-    createdAt?: Date | null;
-    updatedAt?: Date | null;
-    status: 'available' | 'completed';
-    scopeKey: string;
-    windowStart: string;
-    windowEnd: string;
-}
-interface AchievementWithStatus {
-    id: string;
-    title: string;
-    description: string | null;
-    scope: AchievementScopeType;
-    rewardCredits: number;
-    limit: number;
-    completionType: string;
-    completionConfig: unknown;
-    target: unknown;
-    active: boolean;
-    createdAt: Date | null;
-    updatedAt: Date | null;
-    status: 'available' | 'completed';
-    scopeKey: string;
-    windowStart?: string;
-    windowEnd?: string;
-}
-interface AchievementHistoryEntry {
-    achievementId: string;
-    title: string;
-    rewardCredits: number;
-    createdAt: Date;
-    scopeKey: string;
-}
-interface AchievementProgressResponse {
-    achievementId: string;
-    status: 'completed' | 'already_completed';
-    rewardCredits: number;
-    scopeKey: string;
-    createdAt: Date;
-}
-
-/**
- * TimeBack Enums & Literal Types
- *
- * Basic type definitions used throughout the TimeBack integration.
- *
- * @module types/timeback/types
- */
-/**
- * Valid TimeBack subject values for course configuration.
- * These are the supported subject values for OneRoster courses.
- */
-type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
-/**
- * Grade levels per AE OneRoster GradeEnum.
- * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
- */
-type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
-/**
- * Valid Caliper subject values.
- * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
- */
-type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
-/**
- * OneRoster organization types.
- */
-type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-/**
- * Lesson types for PowerPath integration.
- */
-type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
-
-/**
- * TimeBack Configuration Types
- *
- * Configuration interfaces for Organization, Course, Component,
- * Resource, and complete TimeBack setup.
- *
- * @module types/timeback/config
- */
-
-/**
- * Organization configuration for TimeBack (user input - optionals allowed)
- */
-interface OrganizationConfig {
-    /** Display name for your organization */
-    name?: string;
-    /** Organization type */
-    type?: OrganizationType;
-    /** Unique identifier (defaults to Playcademy's org) */
-    identifier?: string;
-}
-/**
- * Course goals for daily student targets
- */
-interface CourseGoals {
-    /** Target XP students should earn per day */
-    dailyXp?: number;
-    /** Target lessons per day */
-    dailyLessons?: number;
-    /** Target active minutes per day */
-    dailyActiveMinutes?: number;
-    /** Target accuracy percentage */
-    dailyAccuracy?: number;
-    /** Target mastered units per day */
-    dailyMasteredUnits?: number;
+interface CourseGoals {
+    /** Target XP students should earn per day */
+    dailyXp?: number;
+    /** Target lessons per day */
+    dailyLessons?: number;
+    /** Target active minutes per day */
+    dailyActiveMinutes?: number;
+    /** Target accuracy percentage */
+    dailyAccuracy?: number;
+    /** Target mastered units per day */
+    dailyMasteredUnits?: number;
 }
 /**
  * Course metrics and totals
@@ -820,169 +538,451 @@ interface TimebackAdminMutationResponse {
 }
 
 /**
- * Inventory & Shop Types
- *
- * Literal types for inventory system. Database row types are in @playcademy/data/types.
+ * Achievement Types
  *
- * @module types/inventory
- */
-/**
- * Item categories available on the platform.
+ * @module types/achievement
  */
-type ItemType = 'currency' | 'badge' | 'trophy' | 'collectible' | 'consumable' | 'unlock' | 'upgrade' | 'accessory' | 'other';
+type AchievementScopeType = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'game' | 'global' | 'map' | 'level' | 'event';
+declare enum AchievementCompletionType {
+    TIME_PLAYED_SESSION = "time_played_session",
+    INTERACTION = "interaction",
+    LEADERBOARD_RANK = "leaderboard_rank",
+    FIRST_SCORE = "first_score",
+    PERSONAL_BEST = "personal_best"
+}
+interface AchievementCurrent {
+    id: string;
+    title: string;
+    description?: string | null;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: string;
+    completionConfig: unknown;
+    target: unknown;
+    active: boolean;
+    createdAt?: Date | null;
+    updatedAt?: Date | null;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart: string;
+    windowEnd: string;
+}
+interface AchievementWithStatus {
+    id: string;
+    title: string;
+    description: string | null;
+    scope: AchievementScopeType;
+    rewardCredits: number;
+    limit: number;
+    completionType: string;
+    completionConfig: unknown;
+    target: unknown;
+    active: boolean;
+    createdAt: Date | null;
+    updatedAt: Date | null;
+    status: 'available' | 'completed';
+    scopeKey: string;
+    windowStart?: string;
+    windowEnd?: string;
+}
+interface AchievementHistoryEntry {
+    achievementId: string;
+    title: string;
+    rewardCredits: number;
+    createdAt: Date;
+    scopeKey: string;
+}
+interface AchievementProgressResponse {
+    achievementId: string;
+    status: 'completed' | 'already_completed';
+    rewardCredits: number;
+    scopeKey: string;
+    createdAt: Date;
+}
 
 /**
- * Map & Placement Types
- *
- * Literal types and JSON shapes for maps. Database row types are in @playcademy/data/types.
+ * Notification Types
  *
- * @module types/map
- */
-/**
- * Allowed map interaction types.
- */
-type InteractionType = 'game_entry' | 'game_registry' | 'info' | 'teleport' | 'door_in' | 'door_out' | 'npc_interaction' | 'quest_trigger';
-/**
- * Metadata for interactive map elements.
+ * @module types/notification
  */
-interface MapElementMetadata {
-    description?: string;
-    title?: string;
-    targetMapIdentifier?: string;
-    targetSpawnTileX?: number;
-    targetSpawnTileY?: number;
-    sourceTiledObjects?: Record<string, unknown>[];
-    [key: string]: unknown;
+
+declare enum NotificationType {
+    ACHIEVEMENT = "achievement",
+    SYSTEM = "system",
+    PROMO = "promo"
 }
-/**
- * Metadata describing how an item should be placed on the map.
- */
-interface PlaceableItemMetadata {
-    tilesWide?: number;
-    tilesHigh?: number;
-    flippable?: boolean;
-    [key: string]: unknown;
+declare enum NotificationStatus {
+    PENDING = "pending",
+    DELIVERED = "delivered",
+    SEEN = "seen",
+    CLICKED = "clicked",
+    DISMISSED = "dismissed",
+    EXPIRED = "expired"
 }
-/**
- * Simplified map data for API responses.
- */
-interface MapData {
-    id: string;
-    identifier: string;
-    displayName: string;
-    description?: string | null;
-    metadata?: Record<string, unknown> | null;
+declare enum NotificationMethod {
+    REALTIME = "realtime",
+    LOGIN = "login",
+    PUSH = "push"
 }
-/**
- * Input for creating a map object.
- */
-interface CreateMapObjectData {
-    itemId: string;
-    worldX: number;
-    worldY: number;
-    width?: number;
-    height?: number;
-    rotation?: number;
-    scale?: number;
-    metadata?: Record<string, unknown>;
+interface NotificationStats {
+    total: number;
+    delivered: number;
+    seen: number;
+    clicked: number;
+    dismissed: number;
+    expired: number;
+    clickThroughRate: number;
 }
 
 /**
- * Character & Avatar Types
+ * User Types
  *
- * Literal types for character system. Database row types are in @playcademy/data/types.
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
  *
- * @module types/character
+ * @module types/user
  */
+type UserRoleEnumType = 'admin' | 'player' | 'developer' | 'teacher';
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type DeveloperStatusValue = DeveloperStatusEnumType;
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface UserEnrollment {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    enrollments: UserEnrollment[];
+}
 /**
- * Character component categories.
+ * OpenID Connect UserInfo claims (NOT a database row).
  */
-type CharacterComponentType = 'body' | 'outfit' | 'hairstyle' | 'eyes' | 'accessory';
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+interface DeveloperStatusResponse {
+    status: DeveloperStatusEnumType;
+}
+/**
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ */
+interface AuthenticatedUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    username: string | null;
+    role: UserRoleEnumType;
+    developerStatus: DeveloperStatusEnumType;
+    characterCreated: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    hasTimebackAccount: boolean;
+    timeback?: UserTimebackData;
+}
+interface GameUser {
+    id: string;
+    name: string | null;
+    role: UserRoleEnumType;
+    username: string | null;
+    email: string | null;
+    timeback?: UserTimebackData;
+}
 
 /**
- * Level & Progression Types
+ * Game Types
  *
- * API response DTOs for level system. Database row types are in @playcademy/data/types.
+ * Literal types and API DTOs. Database row types are in @playcademy/data/types.
  *
- * @module types/level
+ * @module types/game
  */
+type GameType = 'hosted' | 'external';
+type GamePlatform = 'web' | 'godot' | 'unity' | (string & {});
 /**
- * Result of adding XP to a user.
+ * Game manifest file format (manifest.json).
+ * Note: createdAt is a string here because it's parsed from JSON file.
  */
-interface XPAddResult {
-    totalXP: number;
-    newLevel: number;
-    leveledUp: boolean;
-    creditsAwarded: number;
-    xpToNextLevel: number;
+interface ManifestV1 {
+    version: string;
+    platform: string;
+    createdAt: string;
 }
-/**
- * Result of checking whether a level up occurred.
- */
-interface LevelUpCheckResult {
-    newLevel: number;
-    remainingXp: number;
-    leveledUp: boolean;
-    creditsAwarded: number;
-    xpToNextLevel: number;
+/** Log entry captured from seed worker console output */
+interface SeedLogEntry {
+    /** Log level (log, warn, error, info) */
+    level: 'log' | 'warn' | 'error' | 'info';
+    /** Log message content */
+    message: string;
+    /** Milliseconds since seed execution started */
+    timestamp: number;
+}
+/** Structured error details from D1/SQLite errors */
+interface SeedErrorDetails {
+    /** Error category code */
+    code?: 'CONSTRAINT_VIOLATION' | 'SQL_ERROR' | 'DATABASE_BUSY';
+    /** Table name involved in the error */
+    table?: string;
+    /** Constraint name or column that caused the error */
+    constraint?: string;
+    /** Specific constraint type */
+    constraintType?: 'UNIQUE' | 'FOREIGN_KEY' | 'NOT_NULL';
+    /** Token near syntax error */
+    nearToken?: string;
+    /** Specific error type within category */
+    errorType?: 'TABLE_NOT_FOUND' | 'SYNTAX_ERROR';
 }
 /**
- * Level progress API response.
+ * API response for seed operations (what the API returns to the CLI).
+ *
+ * Extends the worker response with deployment metadata.
  */
-interface LevelProgressResponse {
-    level: number;
-    currentXp: number;
-    xpToNextLevel: number;
-    totalXP: number;
+interface SeedResponse {
+    /** Whether the seed completed successfully */
+    success: boolean;
+    /** Unique identifier for the seed worker deployment */
+    deploymentId: string;
+    /** When the seed was executed (ISO 8601 string from JSON serialization) */
+    executedAt: string;
+    /** Captured console output from the seed script */
+    logs?: SeedLogEntry[];
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Error message if seed failed */
+    error?: string;
+    /** Stack trace if seed failed */
+    stack?: string;
+    /** Structured error details if seed failed */
+    details?: SeedErrorDetails;
+}
+interface DomainValidationRecords {
+    ownership?: {
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    ssl?: {
+        txt_name?: string;
+        txt_value?: string;
+    }[];
 }
 
 /**
- * Notification Types
+ * Leaderboard Types
  *
- * @module types/notification
+ * @module types/leaderboard
  */
-
-declare enum NotificationType {
-    ACHIEVEMENT = "achievement",
-    SYSTEM = "system",
-    PROMO = "promo"
+type LeaderboardTimeframe = 'all_time' | 'monthly' | 'weekly' | 'daily';
+interface LeaderboardOptions {
+    timeframe?: LeaderboardTimeframe;
+    limit?: number;
+    offset?: number;
+    gameId?: string;
 }
-declare enum NotificationStatus {
-    PENDING = "pending",
-    DELIVERED = "delivered",
-    SEEN = "seen",
-    CLICKED = "clicked",
-    DISMISSED = "dismissed",
-    EXPIRED = "expired"
+interface LeaderboardEntry {
+    rank: number;
+    userId: string;
+    username: string;
+    userImage?: string | null;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId?: string;
+    gameTitle?: string;
+    gameSlug?: string;
 }
-declare enum NotificationMethod {
-    REALTIME = "realtime",
-    LOGIN = "login",
-    PUSH = "push"
+interface UserRank {
+    rank: number;
+    totalPlayers: number;
+    score: number;
+    percentile: number;
 }
-interface NotificationStats {
-    total: number;
-    delivered: number;
-    seen: number;
-    clicked: number;
-    dismissed: number;
-    expired: number;
-    clickThroughRate: number;
+interface UserRankResponse {
+    rank: number;
+    score: number;
+    userId: string;
+}
+interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: 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;
 }
 
 /**
- * Shop Types
+ * Inventory & Shop Types
  *
- * @module types/shop
+ * Literal types for inventory system. Database row types are in @playcademy/data/types.
+ *
+ * @module types/inventory
  */
 /**
- * Currency display info for shop UI.
+ * Item categories available on the platform.
  */
-interface ShopCurrency {
-    id: string;
-    symbol: string | null;
-    isPrimary: boolean;
-    displayName?: string | null;
+type ItemType = 'currency' | 'badge' | 'trophy' | 'collectible' | 'consumable' | 'unlock' | 'upgrade' | 'accessory' | 'other';
+
+/**
+ * Map & Placement Types
+ *
+ * Literal types and JSON shapes for maps. Database row types are in @playcademy/data/types.
+ *
+ * @module types/map
+ */
+/**
+ * Allowed map interaction types.
+ */
+type InteractionType = 'game_entry' | 'game_registry' | 'info' | 'teleport' | 'door_in' | 'door_out' | 'npc_interaction' | 'quest_trigger';
+/**
+ * Metadata for interactive map elements.
+ */
+interface MapElementMetadata {
+    description?: string;
+    title?: string;
+    targetMapIdentifier?: string;
+    targetSpawnTileX?: number;
+    targetSpawnTileY?: number;
+    sourceTiledObjects?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+/**
+ * Metadata describing how an item should be placed on the map.
+ */
+interface PlaceableItemMetadata {
+    tilesWide?: number;
+    tilesHigh?: number;
+    flippable?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Simplified map data for API responses.
+ */
+interface MapData {
+    id: string;
+    identifier: string;
+    displayName: string;
+    description?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Input for creating a map object.
+ */
+interface CreateMapObjectData {
+    itemId: string;
+    worldX: number;
+    worldY: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    scale?: number;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Character & Avatar Types
+ *
+ * Literal types for character system. Database row types are in @playcademy/data/types.
+ *
+ * @module types/character
+ */
+/**
+ * Character component categories.
+ */
+type CharacterComponentType = 'body' | 'outfit' | 'hairstyle' | 'eyes' | 'accessory';
+
+/**
+ * Level & Progression Types
+ *
+ * API response DTOs for level system. Database row types are in @playcademy/data/types.
+ *
+ * @module types/level
+ */
+/**
+ * Result of adding XP to a user.
+ */
+interface XPAddResult {
+    totalXP: number;
+    newLevel: number;
+    leveledUp: boolean;
+    creditsAwarded: number;
+    xpToNextLevel: number;
+}
+/**
+ * Result of checking whether a level up occurred.
+ */
+interface LevelUpCheckResult {
+    newLevel: number;
+    remainingXp: number;
+    leveledUp: boolean;
+    creditsAwarded: number;
+    xpToNextLevel: number;
+}
+/**
+ * Level progress API response.
+ */
+interface LevelProgressResponse {
+    level: number;
+    currentXp: number;
+    xpToNextLevel: number;
+    totalXP: number;
+}
+
+/**
+ * Shop Types
+ *
+ * @module types/shop
+ */
+/**
+ * Currency display info for shop UI.
+ */
+interface ShopCurrency {
+    id: string;
+    symbol: string | null;
+    isPrimary: boolean;
+    displayName?: string | null;
     imageUrl?: string | null;
 }
 /**
@@ -1068,1326 +1068,226 @@ interface SpriteConfigWithDimensions {
     animations: Record<string, SpriteAnimationFrame>;
 }
 
-/**
- * Base error class for Cademy SDK specific errors.
- */
-declare class PlaycademyError extends Error {
-    constructor(message: string);
-}
-/**
- * Error codes returned by the API.
- * These map to specific error types and HTTP status codes.
- */
-type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'ALREADY_EXISTS' | 'GONE' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_FAILED' | 'TOO_MANY_REQUESTS' | 'RATE_LIMITED' | 'EXPIRED' | 'INTERNAL' | 'INTERNAL_ERROR' | 'NOT_IMPLEMENTED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | string;
-/**
- * Structure of error response bodies returned by API endpoints.
- *
- * @example
- * ```json
- * {
- *   "error": {
- *     "code": "NOT_FOUND",
- *     "message": "Item not found",
- *     "details": { "identifier": "abc123" }
- *   }
- * }
- * ```
- */
-interface ErrorResponseBody {
-    error?: {
-        code?: string;
-        message?: string;
-        details?: unknown;
-    };
-}
-/**
- * API error thrown when a request fails.
- *
- * Contains structured error information from the API response:
- * - `status` - HTTP status code (e.g., 404)
- * - `code` - API error code (e.g., "NOT_FOUND")
- * - `message` - Human-readable error message
- * - `details` - Optional additional error context
- *
- * @example
- * ```typescript
- * try {
- *   await client.games.get('nonexistent')
- * } catch (error) {
- *   if (error instanceof ApiError) {
- *     console.log(error.status)   // 404
- *     console.log(error.code)     // "NOT_FOUND"
- *     console.log(error.message)  // "Game not found"
- *     console.log(error.details)  // { identifier: "nonexistent" }
- *   }
- * }
- * ```
- */
-declare class ApiError extends Error {
-    /**
-     * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
-     * Use this for programmatic error handling.
-     */
-    readonly code: ApiErrorCode;
-    /**
-     * Additional error context from the API.
-     * Structure varies by error type (e.g., validation errors include field details).
-     */
-    readonly details: unknown;
-    /**
-     * Raw response body for debugging.
-     * @internal
-     */
-    readonly rawBody: unknown;
-    readonly status: number;
-    constructor(
-    /** HTTP status code */
-    status: number, 
-    /** API error code */
-    code: ApiErrorCode, 
-    /** Human-readable error message */
-    message: string, 
-    /** Additional error context */
-    details?: unknown, 
-    /** Raw response body */
-    rawBody?: unknown);
-    /**
-     * Create an ApiError from an HTTP response.
-     * Parses the structured error response from the API.
-     *
-     * @internal
-     */
-    static fromResponse(status: number, statusText: string, body: unknown): ApiError;
-    /**
-     * Check if this is a specific error type.
-     *
-     * @example
-     * ```typescript
-     * if (error.is('NOT_FOUND')) {
-     *   // Handle not found
-     * } else if (error.is('VALIDATION_FAILED')) {
-     *   // Handle validation error
-     * }
-     * ```
-     */
-    is(code: ApiErrorCode): boolean;
-    /**
-     * Check if this is a client error (4xx).
-     */
-    isClientError(): boolean;
-    /**
-     * Check if this is a server error (5xx).
-     */
-    isServerError(): boolean;
-    /**
-     * Check if this error is retryable.
-     * Server errors and rate limits are typically retryable.
-     */
-    isRetryable(): boolean;
-}
-/**
- * Extracted error information for display purposes.
- */
-interface ApiErrorInfo {
-    /** HTTP status code */
-    status: number;
-    /** API error code */
-    code: ApiErrorCode;
-    /** Human-readable error message */
-    message: string;
-    /** Additional error context */
-    details?: unknown;
-}
-/**
- * Extract useful error information from an API error.
- * Useful for displaying errors to users in a friendly way.
- *
- * @example
- * ```typescript
- * try {
- *   await client.shop.purchase(itemId)
- * } catch (error) {
- *   const info = extractApiErrorInfo(error)
- *   if (info) {
- *     showToast(`Error: ${info.message}`)
- *   }
- * }
- * ```
- */
-declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
+declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "user";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: drizzle_orm_pg_core.PgColumn<{
+            name: "name";
+            tableName: "user";
+            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;
+        }, {}, {}>;
+        username: drizzle_orm_pg_core.PgColumn<{
+            name: "username";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        email: drizzle_orm_pg_core.PgColumn<{
+            name: "email";
+            tableName: "user";
+            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;
+        }, {}, {}>;
+        timebackId: drizzle_orm_pg_core.PgColumn<{
+            name: "timeback_id";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        emailVerified: drizzle_orm_pg_core.PgColumn<{
+            name: "email_verified";
+            tableName: "user";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        image: drizzle_orm_pg_core.PgColumn<{
+            name: "image";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        role: drizzle_orm_pg_core.PgColumn<{
+            name: "role";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "admin" | "developer" | "player" | "teacher";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["admin", "player", "developer", "teacher"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        developerStatus: drizzle_orm_pg_core.PgColumn<{
+            name: "developer_status";
+            tableName: "user";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "approved" | "none" | "pending";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["none", "pending", "approved"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        characterCreated: drizzle_orm_pg_core.PgColumn<{
+            name: "character_created";
+            tableName: "user";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "user";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 
+interface GameMetadata {
+    description?: string;
+    emoji?: string;
+    [key: string]: unknown;
+}
 /**
- * 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';
-/**
- * Configuration options for ConnectionMonitor.
- *
- * @see {@link ConnectionMonitor} for usage
- */
-interface ConnectionMonitorConfig {
-    /** Base URL for heartbeat pings (e.g., 'https://api.playcademy.com') */
-    baseUrl: string;
-    /** How often to send heartbeat pings in milliseconds (default: 10000) */
-    heartbeatInterval?: number;
-    /** How long to wait for heartbeat response in milliseconds (default: 5000) */
-    heartbeatTimeout?: number;
-    /** Number of consecutive failures before triggering disconnect (default: 2) */
-    failureThreshold?: number;
-    /** Enable periodic heartbeat monitoring (default: true) */
-    enableHeartbeat?: boolean;
-    /** Enable browser online/offline event listeners (default: true) */
-    enableOfflineEvents?: boolean;
-}
-/**
- * Callback function signature for connection state changes.
- *
- * @param state - The new connection state
- * @param reason - Human-readable reason for the state change
- */
-type ConnectionChangeCallback = (state: ConnectionState, reason: string) => void;
-
-/**
- * Connection Monitor
- *
- * Monitors network connectivity using multiple signals:
- * 1. navigator.onLine - Instant offline detection
- * 2. Periodic heartbeat - Detects slow/degraded connections
- * 3. Request failure tracking - Piggybacks on actual API calls
- *
- * Designed for school WiFi environments where connections may be
- * unstable or degraded without fully disconnecting.
- */
-
-/**
- * Monitors network connectivity using multiple signals and notifies callbacks of state changes.
- *
- * The ConnectionMonitor uses a multi-signal approach to detect connection issues:
- *
- * 1. **navigator.onLine events** - Instant detection of hard disconnects
- * 2. **Heartbeat pings** - Periodic checks to detect slow/degraded connections
- * 3. **Request failure tracking** - Piggybacks on actual API calls
- *
- * This comprehensive approach ensures reliable detection across different network
- * failure modes common in school WiFi environments (hard disconnect, slow connection,
- * intermittent failures).
- *
- * @example
- * ```typescript
- * const monitor = new ConnectionMonitor({
- *   baseUrl: 'https://api.playcademy.com',
- *   heartbeatInterval: 10000,  // Check every 10s
- *   failureThreshold: 2         // Trigger after 2 failures
- * })
- *
- * monitor.onChange((state, reason) => {
- *   console.log(`Connection: ${state} - ${reason}`)
- * })
- *
- * monitor.start()
- * ```
- *
- * @see {@link ConnectionManagerConfig} for configuration options
- */
-declare class ConnectionMonitor {
-    private state;
-    private callbacks;
-    private heartbeatInterval?;
-    private consecutiveFailures;
-    private isMonitoring;
-    private config;
-    /**
-     * Creates a new ConnectionMonitor instance.
-     *
-     * The monitor starts in a stopped state. Call `start()` to begin monitoring.
-     *
-     * @param config - Configuration options
-     * @param config.baseUrl - Base URL for heartbeat pings
-     * @param config.heartbeatInterval - How often to check (default: 10000ms)
-     * @param config.heartbeatTimeout - Request timeout (default: 5000ms)
-     * @param config.failureThreshold - Failures before triggering disconnect (default: 2)
-     * @param config.enableHeartbeat - Enable periodic checks (default: true)
-     * @param config.enableOfflineEvents - Listen to browser events (default: true)
-     */
-    constructor(config: ConnectionMonitorConfig);
-    /**
-     * Starts monitoring the connection state.
-     *
-     * Sets up event listeners and begins heartbeat checks based on configuration.
-     * Idempotent - safe to call multiple times.
-     */
-    start(): void;
-    /**
-     * Stops monitoring the connection state and cleans up resources.
-     *
-     * Removes event listeners and clears heartbeat intervals.
-     * Idempotent - safe to call multiple times.
-     */
-    stop(): void;
-    /**
-     * Registers a callback to be notified of all connection state changes.
-     *
-     * The callback fires for all state transitions: online → offline,
-     * offline → degraded, degraded → online, etc.
-     *
-     * @param callback - Function called with (state, reason) when connection changes
-     * @returns Cleanup function to unregister the callback
-     *
-     * @example
-     * ```typescript
-     * const cleanup = monitor.onChange((state, reason) => {
-     *   console.log(`Connection: ${state}`)
-     *   if (state === 'offline') {
-     *     showReconnectingUI()
-     *   }
-     * })
-     *
-     * // Later: cleanup() to unregister
-     * ```
-     */
-    onChange(callback: ConnectionChangeCallback): () => void;
-    /**
-     * Gets the current connection state.
-     *
-     * @returns The current state ('online', 'offline', or 'degraded')
-     */
-    getState(): ConnectionState;
-    /**
-     * Manually triggers an immediate connection check.
-     *
-     * Forces a heartbeat ping to verify connectivity right now, bypassing
-     * the normal interval. Useful before critical operations.
-     *
-     * @returns Promise resolving to the current connection state after the check
-     *
-     * @example
-     * ```typescript
-     * const state = await monitor.checkNow()
-     * if (state !== 'online') {
-     *   alert('Please check your internet connection')
-     * }
-     * ```
-     */
-    checkNow(): Promise<ConnectionState>;
-    /**
-     * Reports a request failure for tracking.
-     *
-     * This should be called from your request wrapper whenever an API call fails.
-     * Only network errors are tracked (TypeError, fetch failures) - HTTP error
-     * responses (4xx, 5xx) are ignored.
-     *
-     * After consecutive failures exceed the threshold, the monitor transitions
-     * to 'degraded' or 'offline' state.
-     *
-     * @param error - The error from the failed request
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   await fetch('/api/data')
-     * } catch (error) {
-     *   monitor.reportRequestFailure(error)
-     *   throw error
-     * }
-     * ```
-     */
-    reportRequestFailure(error: unknown): void;
-    /**
-     * Reports a successful request.
-     *
-     * This should be called from your request wrapper whenever an API call succeeds.
-     * Resets the consecutive failure counter and transitions from 'degraded' to
-     * 'online' if the connection has recovered.
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const result = await fetch('/api/data')
-     *   monitor.reportRequestSuccess()
-     *   return result
-     * } catch (error) {
-     *   monitor.reportRequestFailure(error)
-     *   throw error
-     * }
-     * ```
-     */
-    reportRequestSuccess(): void;
-    private _detectInitialState;
-    private _handleOnline;
-    private _handleOffline;
-    private _startHeartbeat;
-    private _performHeartbeat;
-    private _handleHeartbeatFailure;
-    private _setState;
-}
-
-/**
- * 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.
- */
-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;
-}
-/**
- * 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}`)
-     *   }
-     * })
-     * ```
-     */
-    constructor(config: ConnectionManagerConfig);
-    /**
-     * Gets the current connection state.
-     *
-     * @returns The current connection state ('online', 'offline', or 'degraded')
-     *
-     * @example
-     * ```typescript
-     * const state = manager.getState()
-     * if (state === 'offline') {
-     *   console.log('No connection')
-     * }
-     * ```
-     */
-    getState(): ConnectionState;
-    /**
-     * 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()
-     * }
-     * ```
-     */
-    checkNow(): Promise<ConnectionState>;
-    /**
-     * 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).
-     */
-    reportRequestSuccess(): void;
-    /**
-     * 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
-     */
-    reportRequestFailure(error: unknown): void;
-    /**
-     * 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.
-     *
-     * @param callback - Function to call when connection degrades
-     * @returns Cleanup function to unregister the callback
-     *
-     * @example
-     * ```typescript
-     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
-     *   if (state === 'offline') {
-     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
-     *     saveGameState()
-     *   }
-     * })
-     *
-     * // Later: cleanup() to unregister
-     * ```
-     */
-    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;
-}
-
-/**
- * @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
- */
-
-/**
- * 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 {
-    /**
-     * 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",
-    /**
-     * 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 definition for message handler functions.
- * These functions are called when a specific message type is received.
- *
- * @template T - The type of payload data the handler expects
- * @param payload - The data sent with the message
- */
-type MessageHandler<T = unknown> = (payload: T) => void;
-/**
- * Type mapping that defines the payload structure for each message type.
- * This ensures type safety when sending and receiving messages.
- *
- * **Usage Examples**:
- * ```typescript
- * // Type-safe message sending
- * messaging.send(MessageEvents.INIT, { baseUrl: '/api', token: 'abc', gameId: '123' })
- *
- * // Type-safe message handling
- * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
- *   console.log(`New token expires at: ${new Date(exp)}`)
- * })
- * ```
- */
-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;
-}
-/**
- * **PlaycademyMessaging Class**
- *
- * This is the core messaging system that handles all communication in the Playcademy platform.
- * It automatically detects the runtime environment and chooses the appropriate transport method.
- *
- * **Key Features**:
- * 1. **Automatic Transport Selection**: Detects iframe vs local context and uses appropriate method
- * 2. **Type Safety**: Full TypeScript support with payload type checking
- * 3. **Bidirectional Communication**: Handles both parent→game and game→parent messages
- * 4. **Event Cleanup**: Proper listener management to prevent memory leaks
- *
- * **Transport Methods**:
- * - **postMessage**: Used for iframe-to-parent communication (production/development)
- * - **CustomEvent**: Used for local same-context communication (local development)
- *
- * **Runtime Detection Logic**:
- * - If `window.self !== window.top`: We're in an iframe, use postMessage
- * - If `window.self === window.top`: We're in the same context, use CustomEvent
- *
- * **Example Usage**:
- * ```typescript
- * // Send a message (automatically chooses transport)
- * messaging.send(MessageEvents.READY, undefined)
- *
- * // Listen for messages (handles both transports)
- * messaging.listen(MessageEvents.INIT, (payload) => {
- *   console.log('Game initialized with:', payload)
- * })
- *
- * // Clean up listeners
- * messaging.unlisten(MessageEvents.INIT, handler)
- * ```
- */
-declare class PlaycademyMessaging {
-    /**
-     * Internal storage for message listeners.
-     *
-     * **Structure Explanation**:
-     * - Outer Map: MessageEvents → Map of handlers for that event type
-     * - Inner Map: MessageHandler → Object containing both listener types
-     * - Object: { postMessage: EventListener, customEvent: EventListener }
-     *
-     * **Why Two Listeners Per Handler?**:
-     * Since we don't know at registration time which transport will be used,
-     * we register both a postMessage listener and a CustomEvent listener.
-     * The appropriate one will be triggered based on the runtime context.
-     */
-    private listeners;
-    /**
-     * **Send Message Method**
-     *
-     * Sends a message using the appropriate transport method based on the runtime context.
-     * This is the main public API for sending messages in the Playcademy system.
-     *
-     * **How It Works**:
-     * 1. Analyzes the message type and current runtime context
-     * 2. Determines if we're in an iframe and if this message should use postMessage
-     * 3. Routes to the appropriate transport method (postMessage or CustomEvent)
-     *
-     * **Transport Selection Logic**:
-     * - **postMessage**: Used when game is in iframe and sending to parent, 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;
-    /**
-     * **Remove Message Listener Method**
-     *
-     * Removes a previously registered message listener to prevent memory leaks and unwanted callbacks.
-     * This method cleans up both the postMessage and CustomEvent listeners that were registered.
-     *
-     * **Why Clean Up Both Listeners?**:
-     * When we registered the listener with `listen()`, we created two browser event listeners:
-     * 1. A 'message' event listener for postMessage communication
-     * 2. A custom event listener for local CustomEvent communication
-     *
-     * Both must be removed to prevent memory leaks and ensure the handler is completely unregistered.
-     *
-     * **Memory Management**:
-     * - Removes both event listeners from the browser
-     * - Cleans up internal tracking maps
-     * - If no more handlers exist for a message type, removes the entire type entry
-     *
-     * **Safe to Call Multiple Times**:
-     * This method is idempotent - calling it multiple times with the same handler is safe.
-     *
-     * @template K - The message event type (ensures type safety)
-     * @param type - The message event type to stop listening for
-     * @param handler - The exact handler function that was passed to listen()
-     *
-     * @example
-     * ```typescript
-     * // Register a handler
-     * const handleInit = (payload) => console.log('Game initialized')
-     * messaging.listen(MessageEvents.INIT, handleInit)
-     *
-     * // Later, remove the handler
-     * messaging.unlisten(MessageEvents.INIT, handleInit)
-     *
-     * // Safe to call multiple times
-     * messaging.unlisten(MessageEvents.INIT, handleInit) // No error
-     * ```
-     */
-    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
-    /**
-     * **Get Messaging Context Method**
-     *
-     * Analyzes the current runtime environment and message type to determine the appropriate
-     * transport method and configuration for sending messages.
-     *
-     * **Runtime Environment Detection**:
-     * The method detects whether the code is running in an iframe by comparing:
-     * - `window.self`: Reference to the current window
-     * - `window.top`: Reference to the topmost window in the hierarchy
-     *
-     * If they're different, we're in an iframe. If they're the same, we're in the top-level window.
-     *
-     * **Message Direction Analysis**:
-     * Different message types flow in different directions:
-     * - **Game → Parent**: READY, EXIT, TELEMETRY (use postMessage when in iframe)
-     * - **Parent → Game**: INIT, TOKEN_REFRESH, PAUSE, etc. (use CustomEvent in local dev, 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;
-}
-/**
- * **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;
-
-declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "user";
-    schema: undefined;
-    columns: {
-        id: drizzle_orm_pg_core.PgColumn<{
-            name: "id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: true;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        name: drizzle_orm_pg_core.PgColumn<{
-            name: "name";
-            tableName: "user";
-            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;
-        }, {}, {}>;
-        username: drizzle_orm_pg_core.PgColumn<{
-            name: "username";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        email: drizzle_orm_pg_core.PgColumn<{
-            name: "email";
-            tableName: "user";
-            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;
-        }, {}, {}>;
-        timebackId: drizzle_orm_pg_core.PgColumn<{
-            name: "timeback_id";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        emailVerified: drizzle_orm_pg_core.PgColumn<{
-            name: "email_verified";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        image: drizzle_orm_pg_core.PgColumn<{
-            name: "image";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        role: drizzle_orm_pg_core.PgColumn<{
-            name: "role";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "admin" | "developer" | "player" | "teacher";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["admin", "player", "developer", "teacher"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        developerStatus: drizzle_orm_pg_core.PgColumn<{
-            name: "developer_status";
-            tableName: "user";
-            dataType: "string";
-            columnType: "PgEnumColumn";
-            data: "approved" | "none" | "pending";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["none", "pending", "approved"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        characterCreated: drizzle_orm_pg_core.PgColumn<{
-            name: "character_created";
-            tableName: "user";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        createdAt: drizzle_orm_pg_core.PgColumn<{
-            name: "created_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
-            tableName: "user";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
-
-interface GameMetadata {
-    description?: string;
-    emoji?: string;
-    [key: string]: unknown;
-}
-/**
- * DNS validation records for custom hostname
- * Structure for the validationRecords JSON field in game_custom_hostnames table
+ * DNS validation records for custom hostname
+ * Structure for the validationRecords JSON field in game_custom_hostnames table
  */
 interface CustomHostnameValidationRecords {
     /** TXT record for ownership verification */
@@ -5616,267 +4516,1367 @@ type UpdateCurrencyInput = z.infer<typeof UpdateCurrencySchema>;
 type InsertShopListingInput = z.infer<typeof InsertShopListingSchema>;
 type UpdateShopListingInput = z.infer<typeof UpdateShopListingSchema>;
 
-type MapRow = typeof maps.$inferSelect;
-type MapElementRow = typeof mapElements.$inferSelect;
-type MapObjectRow = typeof mapObjects.$inferSelect;
+type MapRow = typeof maps.$inferSelect;
+type MapElementRow = typeof mapElements.$inferSelect;
+type MapObjectRow = typeof mapObjects.$inferSelect;
+
+type UserRow = typeof users.$inferSelect;
+
+/**
+ * Cross-Domain Composite Types
+ * Types that combine data from multiple domains
+ */
+type CharacterComponentWithSpriteUrl = CharacterComponentRow & {
+    spriteSheetUrl: string;
+};
+type InventoryItemWithItem = InventoryItemRow & {
+    item: ItemRow;
+};
+/**
+ * Game with optional manifest metadata from build tools
+ */
+type FetchedGame = (HostedGame | ExternalGame | GameRow) & {
+    manifest?: ManifestV1;
+};
+/**
+ * Session Bootstrap Payload Types
+ * Complex types that combine user, inventory, game, and map data for client initialization
+ */
+interface PlayerProfile {
+    userId: UserRow['id'];
+    username: UserRow['username'];
+    name: UserRow['name'];
+    image?: UserRow['image'];
+    role?: UserRow['role'];
+    characterCreated?: UserRow['characterCreated'];
+    hasTimebackAccount?: boolean;
+}
+interface PlayerCurrency {
+    currencySystemId: CurrencyRow['id'];
+    itemId: ItemRow['id'];
+    name: ItemRow['displayName'];
+    symbol?: CurrencyRow['symbol'];
+    imageUrl?: ItemRow['imageUrl'];
+    isPrimary: CurrencyRow['isPrimary'];
+    balance: number;
+}
+interface PlayerInventoryItem {
+    inventoryItemEntryId: InventoryItemRow['id'];
+    item: ItemRow;
+    quantity: InventoryItemRow['quantity'];
+    updatedAt: InventoryItemRow['updatedAt'];
+}
+interface PlayerLocation {
+    mapIdentifier: MapRow['identifier'];
+    mapDisplayName: MapRow['displayName'];
+    tileX?: number;
+    tileY?: number;
+    worldX?: number;
+    worldY?: number;
+    direction?: 'up' | 'down' | 'left' | 'right';
+}
+interface PlayerSessionPayload {
+    profile: PlayerProfile;
+    currencies: PlayerCurrency[];
+    inventory: PlayerInventoryItem[];
+    ownedGameIds: Game['id'][];
+    currentLocation?: PlayerLocation;
+    characterCreated?: UserRow['characterCreated'];
+    playerCharacter?: PlayerCharacterRow | null;
+}
+/**
+ * Map-related Composite Types
+ * DB row + joined game/item data
+ */
+type MapElementWithGame = MapElementRow & {
+    game: {
+        id: string;
+        displayName: string;
+    } | null;
+};
+type MapObjectWithItem = MapObjectRow & {
+    item: {
+        id: string;
+        slug: string;
+        displayName: string;
+        description?: string | null;
+        imageUrl?: string | null;
+        isPlaceable: boolean;
+        metadata?: PlaceableItemMetadata | null;
+    };
+};
+/**
+ * Game custom hostname with validation records
+ */
+type GameCustomHostname = GameCustomHostnameRow & {
+    validationRecords?: DomainValidationRecords;
+};
+
+type UserLevelRow = typeof userLevels.$inferSelect;
+type LevelConfigRow = typeof levelConfigs.$inferSelect;
+type UserLevelWithConfig = UserLevelRow & {
+    xpToNextLevel: number;
+    nextLevelConfig?: LevelConfigRow;
+};
+
+type SpriteTemplateRow = typeof spriteTemplates.$inferSelect;
+
+type NotificationRow = InferSelectModel<typeof notifications>;
+
+/**
+ * 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';
+/**
+ * Configuration options for ConnectionMonitor.
+ *
+ * @see {@link ConnectionMonitor} for usage
+ */
+interface ConnectionMonitorConfig {
+    /** Base URL for heartbeat pings (e.g., 'https://api.playcademy.com') */
+    baseUrl: string;
+    /** How often to send heartbeat pings in milliseconds (default: 10000) */
+    heartbeatInterval?: number;
+    /** How long to wait for heartbeat response in milliseconds (default: 5000) */
+    heartbeatTimeout?: number;
+    /** Number of consecutive failures before triggering disconnect (default: 2) */
+    failureThreshold?: number;
+    /** Enable periodic heartbeat monitoring (default: true) */
+    enableHeartbeat?: boolean;
+    /** Enable browser online/offline event listeners (default: true) */
+    enableOfflineEvents?: boolean;
+}
+/**
+ * Callback function signature for connection state changes.
+ *
+ * @param state - The new connection state
+ * @param reason - Human-readable reason for the state change
+ */
+type ConnectionChangeCallback = (state: ConnectionState, reason: string) => void;
+
+/**
+ * Connection Monitor
+ *
+ * Monitors network connectivity using multiple signals:
+ * 1. navigator.onLine - Instant offline detection
+ * 2. Periodic heartbeat - Detects slow/degraded connections
+ * 3. Request failure tracking - Piggybacks on actual API calls
+ *
+ * Designed for school WiFi environments where connections may be
+ * unstable or degraded without fully disconnecting.
+ */
+
+/**
+ * Monitors network connectivity using multiple signals and notifies callbacks of state changes.
+ *
+ * The ConnectionMonitor uses a multi-signal approach to detect connection issues:
+ *
+ * 1. **navigator.onLine events** - Instant detection of hard disconnects
+ * 2. **Heartbeat pings** - Periodic checks to detect slow/degraded connections
+ * 3. **Request failure tracking** - Piggybacks on actual API calls
+ *
+ * This comprehensive approach ensures reliable detection across different network
+ * failure modes common in school WiFi environments (hard disconnect, slow connection,
+ * intermittent failures).
+ *
+ * @example
+ * ```typescript
+ * const monitor = new ConnectionMonitor({
+ *   baseUrl: 'https://api.playcademy.com',
+ *   heartbeatInterval: 10000,  // Check every 10s
+ *   failureThreshold: 2         // Trigger after 2 failures
+ * })
+ *
+ * monitor.onChange((state, reason) => {
+ *   console.log(`Connection: ${state} - ${reason}`)
+ * })
+ *
+ * monitor.start()
+ * ```
+ *
+ * @see {@link ConnectionManagerConfig} for configuration options
+ */
+declare class ConnectionMonitor {
+    private state;
+    private callbacks;
+    private heartbeatInterval?;
+    private consecutiveFailures;
+    private isMonitoring;
+    private config;
+    /**
+     * Creates a new ConnectionMonitor instance.
+     *
+     * The monitor starts in a stopped state. Call `start()` to begin monitoring.
+     *
+     * @param config - Configuration options
+     * @param config.baseUrl - Base URL for heartbeat pings
+     * @param config.heartbeatInterval - How often to check (default: 10000ms)
+     * @param config.heartbeatTimeout - Request timeout (default: 5000ms)
+     * @param config.failureThreshold - Failures before triggering disconnect (default: 2)
+     * @param config.enableHeartbeat - Enable periodic checks (default: true)
+     * @param config.enableOfflineEvents - Listen to browser events (default: true)
+     */
+    constructor(config: ConnectionMonitorConfig);
+    /**
+     * Starts monitoring the connection state.
+     *
+     * Sets up event listeners and begins heartbeat checks based on configuration.
+     * Idempotent - safe to call multiple times.
+     */
+    start(): void;
+    /**
+     * Stops monitoring the connection state and cleans up resources.
+     *
+     * Removes event listeners and clears heartbeat intervals.
+     * Idempotent - safe to call multiple times.
+     */
+    stop(): void;
+    /**
+     * Registers a callback to be notified of all connection state changes.
+     *
+     * The callback fires for all state transitions: online → offline,
+     * offline → degraded, degraded → online, etc.
+     *
+     * @param callback - Function called with (state, reason) when connection changes
+     * @returns Cleanup function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const cleanup = monitor.onChange((state, reason) => {
+     *   console.log(`Connection: ${state}`)
+     *   if (state === 'offline') {
+     *     showReconnectingUI()
+     *   }
+     * })
+     *
+     * // Later: cleanup() to unregister
+     * ```
+     */
+    onChange(callback: ConnectionChangeCallback): () => void;
+    /**
+     * Gets the current connection state.
+     *
+     * @returns The current state ('online', 'offline', or 'degraded')
+     */
+    getState(): ConnectionState;
+    /**
+     * Manually triggers an immediate connection check.
+     *
+     * Forces a heartbeat ping to verify connectivity right now, bypassing
+     * the normal interval. Useful before critical operations.
+     *
+     * @returns Promise resolving to the current connection state after the check
+     *
+     * @example
+     * ```typescript
+     * const state = await monitor.checkNow()
+     * if (state !== 'online') {
+     *   alert('Please check your internet connection')
+     * }
+     * ```
+     */
+    checkNow(): Promise<ConnectionState>;
+    /**
+     * Reports a request failure for tracking.
+     *
+     * This should be called from your request wrapper whenever an API call fails.
+     * Only network errors are tracked (TypeError, fetch failures) - HTTP error
+     * responses (4xx, 5xx) are ignored.
+     *
+     * After consecutive failures exceed the threshold, the monitor transitions
+     * to 'degraded' or 'offline' state.
+     *
+     * @param error - The error from the failed request
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await fetch('/api/data')
+     * } catch (error) {
+     *   monitor.reportRequestFailure(error)
+     *   throw error
+     * }
+     * ```
+     */
+    reportRequestFailure(error: unknown): void;
+    /**
+     * Reports a successful request.
+     *
+     * This should be called from your request wrapper whenever an API call succeeds.
+     * Resets the consecutive failure counter and transitions from 'degraded' to
+     * 'online' if the connection has recovered.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await fetch('/api/data')
+     *   monitor.reportRequestSuccess()
+     *   return result
+     * } catch (error) {
+     *   monitor.reportRequestFailure(error)
+     *   throw error
+     * }
+     * ```
+     */
+    reportRequestSuccess(): void;
+    private _detectInitialState;
+    private _handleOnline;
+    private _handleOffline;
+    private _startHeartbeat;
+    private _performHeartbeat;
+    private _handleHeartbeatFailure;
+    private _setState;
+}
+
+/**
+ * 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).
+ */
 
-type UserRow = typeof users.$inferSelect;
+/**
+ * Configuration for the ConnectionManager.
+ */
+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;
+}
+/**
+ * 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}`)
+     *   }
+     * })
+     * ```
+     */
+    constructor(config: ConnectionManagerConfig);
+    /**
+     * Gets the current connection state.
+     *
+     * @returns The current connection state ('online', 'offline', or 'degraded')
+     *
+     * @example
+     * ```typescript
+     * const state = manager.getState()
+     * if (state === 'offline') {
+     *   console.log('No connection')
+     * }
+     * ```
+     */
+    getState(): ConnectionState;
+    /**
+     * 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()
+     * }
+     * ```
+     */
+    checkNow(): Promise<ConnectionState>;
+    /**
+     * 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).
+     */
+    reportRequestSuccess(): void;
+    /**
+     * 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
+     */
+    reportRequestFailure(error: unknown): void;
+    /**
+     * 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.
+     *
+     * @param callback - Function to call when connection degrades
+     * @returns Cleanup function to unregister the callback
+     *
+     * @example
+     * ```typescript
+     * const cleanup = manager.onDisconnect(({ state, reason, displayAlert }) => {
+     *   if (state === 'offline') {
+     *     displayAlert?.('Connection lost. Saving your progress...', { type: 'error' })
+     *     saveGameState()
+     *   }
+     * })
+     *
+     * // Later: cleanup() to unregister
+     * ```
+     */
+    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;
+}
 
 /**
- * Cross-Domain Composite Types
- * Types that combine data from multiple domains
+ * @fileoverview Authentication Strategy Pattern
+ *
+ * Provides different authentication strategies for the Playcademy SDK.
+ * Each strategy knows how to add its authentication headers to requests.
  */
-type CharacterComponentWithSpriteUrl = CharacterComponentRow & {
-    spriteSheetUrl: string;
-};
-type InventoryItemWithItem = InventoryItemRow & {
-    item: ItemRow;
-};
+
 /**
- * Game with optional manifest metadata from build tools
+ * Base interface for authentication strategies
  */
-type FetchedGame = (HostedGame | ExternalGame | GameRow) & {
-    manifest?: ManifestV1;
-};
+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>;
+}
+
 /**
- * Session Bootstrap Payload Types
- * Complex types that combine user, inventory, game, and map data for client initialization
+ * 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).
  */
-interface PlayerProfile {
-    userId: UserRow['id'];
-    username: UserRow['username'];
-    name: UserRow['name'];
-    image?: UserRow['image'];
-    role?: UserRow['role'];
-    characterCreated?: UserRow['characterCreated'];
-    hasTimebackAccount?: boolean;
-}
-interface PlayerCurrency {
-    currencySystemId: CurrencyRow['id'];
-    itemId: ItemRow['id'];
-    name: ItemRow['displayName'];
-    symbol?: CurrencyRow['symbol'];
-    imageUrl?: ItemRow['imageUrl'];
-    isPrimary: CurrencyRow['isPrimary'];
-    balance: number;
-}
-interface PlayerInventoryItem {
-    inventoryItemEntryId: InventoryItemRow['id'];
-    item: ItemRow;
-    quantity: InventoryItemRow['quantity'];
-    updatedAt: InventoryItemRow['updatedAt'];
+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;
+    }): 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>, raw?: boolean): 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>;
+        };
+    };
 }
-interface PlayerLocation {
-    mapIdentifier: MapRow['identifier'];
-    mapDisplayName: MapRow['displayName'];
-    tileX?: number;
-    tileY?: number;
-    worldX?: number;
-    worldY?: number;
-    direction?: 'up' | 'down' | 'left' | 'right';
+
+/**
+ * Base error class for Cademy SDK specific errors.
+ */
+declare class PlaycademyError extends Error {
+    constructor(message: string);
 }
-interface PlayerSessionPayload {
-    profile: PlayerProfile;
-    currencies: PlayerCurrency[];
-    inventory: PlayerInventoryItem[];
-    ownedGameIds: Game['id'][];
-    currentLocation?: PlayerLocation;
-    characterCreated?: UserRow['characterCreated'];
-    playerCharacter?: PlayerCharacterRow | null;
+/**
+ * Error codes returned by the API.
+ * These map to specific error types and HTTP status codes.
+ */
+type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'ALREADY_EXISTS' | 'GONE' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'VALIDATION_FAILED' | 'TOO_MANY_REQUESTS' | 'RATE_LIMITED' | 'EXPIRED' | 'INTERNAL' | 'INTERNAL_ERROR' | 'NOT_IMPLEMENTED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | string;
+/**
+ * Structure of error response bodies returned by API endpoints.
+ *
+ * @example
+ * ```json
+ * {
+ *   "error": {
+ *     "code": "NOT_FOUND",
+ *     "message": "Item not found",
+ *     "details": { "identifier": "abc123" }
+ *   }
+ * }
+ * ```
+ */
+interface ErrorResponseBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
 }
 /**
- * Map-related Composite Types
- * DB row + joined game/item data
+ * API error thrown when a request fails.
+ *
+ * Contains structured error information from the API response:
+ * - `status` - HTTP status code (e.g., 404)
+ * - `code` - API error code (e.g., "NOT_FOUND")
+ * - `message` - Human-readable error message
+ * - `details` - Optional additional error context
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.games.get('nonexistent')
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(error.status)   // 404
+ *     console.log(error.code)     // "NOT_FOUND"
+ *     console.log(error.message)  // "Game not found"
+ *     console.log(error.details)  // { identifier: "nonexistent" }
+ *   }
+ * }
+ * ```
  */
-type MapElementWithGame = MapElementRow & {
-    game: {
-        id: string;
-        displayName: string;
-    } | null;
-};
-type MapObjectWithItem = MapObjectRow & {
-    item: {
-        id: string;
-        slug: string;
-        displayName: string;
-        description?: string | null;
-        imageUrl?: string | null;
-        isPlaceable: boolean;
-        metadata?: PlaceableItemMetadata | null;
-    };
-};
+declare class ApiError extends Error {
+    /**
+     * API error code (e.g., "NOT_FOUND", "VALIDATION_FAILED").
+     * Use this for programmatic error handling.
+     */
+    readonly code: ApiErrorCode;
+    /**
+     * Additional error context from the API.
+     * Structure varies by error type (e.g., validation errors include field details).
+     */
+    readonly details: unknown;
+    /**
+     * Raw response body for debugging.
+     * @internal
+     */
+    readonly rawBody: unknown;
+    readonly status: number;
+    constructor(
+    /** HTTP status code */
+    status: number, 
+    /** API error code */
+    code: ApiErrorCode, 
+    /** Human-readable error message */
+    message: string, 
+    /** Additional error context */
+    details?: unknown, 
+    /** Raw response body */
+    rawBody?: unknown);
+    /**
+     * Create an ApiError from an HTTP response.
+     * Parses the structured error response from the API.
+     *
+     * @internal
+     */
+    static fromResponse(status: number, statusText: string, body: unknown): ApiError;
+    /**
+     * Check if this is a specific error type.
+     *
+     * @example
+     * ```typescript
+     * if (error.is('NOT_FOUND')) {
+     *   // Handle not found
+     * } else if (error.is('VALIDATION_FAILED')) {
+     *   // Handle validation error
+     * }
+     * ```
+     */
+    is(code: ApiErrorCode): boolean;
+    /**
+     * Check if this is a client error (4xx).
+     */
+    isClientError(): boolean;
+    /**
+     * Check if this is a server error (5xx).
+     */
+    isServerError(): boolean;
+    /**
+     * Check if this error is retryable.
+     * Server errors and rate limits are typically retryable.
+     */
+    isRetryable(): boolean;
+}
 /**
- * Game custom hostname with validation records
+ * Extracted error information for display purposes.
  */
-type GameCustomHostname = GameCustomHostnameRow & {
-    validationRecords?: DomainValidationRecords;
-};
-
-type UserLevelRow = typeof userLevels.$inferSelect;
-type LevelConfigRow = typeof levelConfigs.$inferSelect;
-type UserLevelWithConfig = UserLevelRow & {
-    xpToNextLevel: number;
-    nextLevelConfig?: LevelConfigRow;
-};
-
-type SpriteTemplateRow = typeof spriteTemplates.$inferSelect;
-
-type NotificationRow = InferSelectModel<typeof notifications>;
-
+interface ApiErrorInfo {
+    /** HTTP status code */
+    status: number;
+    /** API error code */
+    code: ApiErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error context */
+    details?: unknown;
+}
 /**
- * @fileoverview Authentication Strategy Pattern
+ * Extract useful error information from an API error.
+ * Useful for displaying errors to users in a friendly way.
  *
- * Provides different authentication strategies for the Playcademy SDK.
- * Each strategy knows how to add its authentication headers to requests.
+ * @example
+ * ```typescript
+ * try {
+ *   await client.shop.purchase(itemId)
+ * } catch (error) {
+ *   const info = extractApiErrorInfo(error)
+ *   if (info) {
+ *     showToast(`Error: ${info.message}`)
+ *   }
+ * }
+ * ```
  */
+declare function extractApiErrorInfo(error: unknown): ApiErrorInfo | null;
 
 /**
- * Base interface for authentication strategies
+ * @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
  */
-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.
+ * Enumeration of all message types used in the Playcademy messaging system.
  *
- * Extended by PlaycademyClient (game SDK) and PlaycademyInternalClient (platform SDK).
+ * **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 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;
+declare enum MessageEvents {
     /**
-     * Internal session manager for automatic session lifecycle.
-     * @private
-     * @internal
+     * Initializes the game with authentication context and configuration.
+     * Sent immediately after game iframe loads.
+     * Payload:
+     * - `baseUrl`: string
+     * - `token`: string
+     * - `gameId`: string
      */
-    protected _sessionManager: {
-        startSession: (gameId: string) => Promise<{
-            sessionId: string;
-        }>;
-        endSession: (sessionId: string, gameId: string) => Promise<void>;
-    };
-    constructor(config?: Partial<ClientConfig>);
+    INIT = "PLAYCADEMY_INIT",
     /**
-     * Gets the effective base URL for API requests.
+     * Updates the game's authentication token before it expires.
+     * Sent periodically to maintain valid authentication.
+     * Payload:
+     * - `token`: string
+     * - `exp`: number
      */
-    getBaseUrl(): string;
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
     /**
-     * Gets the effective game backend URL for integration requests.
+     * Pauses game execution (e.g., when user switches tabs).
+     * Game should pause timers, animations, and user input.
+     * Payload: void
      */
-    protected getGameBackendUrl(): string;
+    PAUSE = "PLAYCADEMY_PAUSE",
     /**
-     * Simple ping method for testing connectivity.
+     * Resumes game execution after being paused.
+     * Game should restore timers, animations, and user input.
+     * Payload: void
      */
-    ping(): string;
+    RESUME = "PLAYCADEMY_RESUME",
     /**
-     * Sets the authentication token for API requests.
+     * Forces immediate game termination (emergency exit).
+     * Game should clean up resources and exit immediately.
+     * Payload: void
      */
-    setToken(token: string | null, tokenType?: TokenType): void;
-    setLaunchId(launchId: string | null | undefined): void;
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
     /**
-     * Gets the current token type.
+     * 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)
      */
-    getTokenType(): TokenType;
+    OVERLAY = "PLAYCADEMY_OVERLAY",
     /**
-     * Gets the current authentication token.
+     * Broadcasts connection state changes to games.
+     * Sent by platform when network connectivity changes.
+     * Payload:
+     * - `state`: 'online' | 'offline' | 'degraded'
+     * - `reason`: string
      */
-    getToken(): string | null;
+    CONNECTION_STATE = "PLAYCADEMY_CONNECTION_STATE",
     /**
-     * Checks if the client has a valid API token.
+     * Game has finished loading and is ready to receive messages.
+     * Sent once after game initialization is complete.
+     * Payload: void
      */
-    isAuthenticated(): boolean;
+    READY = "PLAYCADEMY_READY",
     /**
-     * Registers a callback to be called when authentication state changes.
+     * Game requests to be closed/exited.
+     * Sent when user clicks exit button or game naturally ends.
+     * Payload: void
      */
-    onAuthChange(callback: (token: string | null) => void): void;
+    EXIT = "PLAYCADEMY_EXIT",
     /**
-     * Registers a callback to be called when connection issues are detected.
+     * Game reports performance telemetry data.
+     * Sent periodically for monitoring and analytics.
+     * Payload:
+     * - `fps`: number
+     * - `mem`: number
      */
-    onDisconnect(callback: (context: DisconnectContext) => void | Promise<void>): () => void;
+    TELEMETRY = "PLAYCADEMY_TELEMETRY",
     /**
-     * Gets the current connection state.
+     * Game reports key events to parent.
+     * Sent when certain keys are pressed within the game iframe.
+     * Payload:
+     * - `key`: string
+     * - `code?`: string
+     * - `type`: 'keydown' | 'keyup'
      */
-    getConnectionState(): ConnectionState | 'unknown';
+    KEY_EVENT = "PLAYCADEMY_KEY_EVENT",
     /**
-     * Manually triggers a connection check immediately.
+     * 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 }`
      */
-    checkConnection(): Promise<ConnectionState | 'unknown'>;
+    DISPLAY_ALERT = "PLAYCADEMY_DISPLAY_ALERT",
     /**
-     * Sets the authentication context for the client.
-     * @internal
+     * Notifies about authentication state changes.
+     * Can be sent in both directions depending on auth flow.
+     * Payload:
+     * - `authenticated`: boolean
+     * - `user`: UserInfo | null
+     * - `error`: Error | null
      */
-    _setAuthContext(context: {
-        isInIframe: boolean;
-    }): void;
+    AUTH_STATE_CHANGE = "PLAYCADEMY_AUTH_STATE_CHANGE",
     /**
-     * Registers an event listener for client events.
+     * 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)
      */
-    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
+    AUTH_CALLBACK = "PLAYCADEMY_AUTH_CALLBACK"
+}
+/**
+ * Type definition for message handler functions.
+ * These functions are called when a specific message type is received.
+ *
+ * @template T - The type of payload data the handler expects
+ * @param payload - The data sent with the message
+ */
+type MessageHandler<T = unknown> = (payload: T) => void;
+/**
+ * Type mapping that defines the payload structure for each message type.
+ * This ensures type safety when sending and receiving messages.
+ *
+ * **Usage Examples**:
+ * ```typescript
+ * // Type-safe message sending
+ * messaging.send(MessageEvents.INIT, { baseUrl: '/api', token: 'abc', gameId: '123' })
+ *
+ * // Type-safe message handling
+ * messaging.listen(MessageEvents.TOKEN_REFRESH, ({ token, exp }) => {
+ *   console.log(`New token expires at: ${new Date(exp)}`)
+ * })
+ * ```
+ */
+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;
+}
+/**
+ * **PlaycademyMessaging Class**
+ *
+ * This is the core messaging system that handles all communication in the Playcademy platform.
+ * It automatically detects the runtime environment and chooses the appropriate transport method.
+ *
+ * **Key Features**:
+ * 1. **Automatic Transport Selection**: Detects iframe vs local context and uses appropriate method
+ * 2. **Type Safety**: Full TypeScript support with payload type checking
+ * 3. **Bidirectional Communication**: Handles both parent→game and game→parent messages
+ * 4. **Event Cleanup**: Proper listener management to prevent memory leaks
+ *
+ * **Transport Methods**:
+ * - **postMessage**: Used for iframe-to-parent communication (production/development)
+ * - **CustomEvent**: Used for local same-context communication (local development)
+ *
+ * **Runtime Detection Logic**:
+ * - If `window.self !== window.top`: We're in an iframe, use postMessage
+ * - If `window.self === window.top`: We're in the same context, use CustomEvent
+ *
+ * **Example Usage**:
+ * ```typescript
+ * // Send a message (automatically chooses transport)
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for messages (handles both transports)
+ * messaging.listen(MessageEvents.INIT, (payload) => {
+ *   console.log('Game initialized with:', payload)
+ * })
+ *
+ * // Clean up listeners
+ * messaging.unlisten(MessageEvents.INIT, handler)
+ * ```
+ */
+declare class PlaycademyMessaging {
     /**
-     * Emits an event to all registered listeners.
+     * 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.
      */
-    protected emit<E extends keyof ClientEvents>(event: E, payload: ClientEvents[E]): void;
+    private listeners;
     /**
-     * Makes an authenticated HTTP request to the platform API.
+     * **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
+     * ```
      */
-    protected request<T>(path: string, method: Method, options?: {
-        body?: unknown;
-        headers?: Record<string, string>;
-        raw?: boolean;
-    }): Promise<T>;
+    send<K extends MessageEvents>(type: K, payload: MessageEventMap[K], options?: {
+        target?: Window;
+        origin?: string;
+    }): void;
     /**
-     * Makes an authenticated HTTP request to the game's backend Worker.
+     * **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)
+     * })
+     * ```
      */
-    protected requestGameBackend<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>, raw?: boolean): Promise<T>;
+    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
     /**
-     * Ensures a gameId is available, throwing an error if not.
+     * **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
+     * ```
      */
-    protected _ensureGameId(): string;
+    unlisten<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
     /**
-     * Detects and sets the authentication context (iframe vs standalone).
+     * **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 _detectAuthContext;
+    private getMessagingContext;
     /**
-     * Initializes connection monitoring if enabled.
+     * **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 _initializeConnectionMonitor;
-    private _initializeInternalSession;
+    private sendViaPostMessage;
     /**
-     * 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
+     * **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'
+     * })
+     * ```
      */
-    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>;
-        };
-    };
+    private sendViaCustomEvent;
 }
+/**
+ * **Playcademy Messaging Singleton**
+ *
+ * This is the main messaging instance used throughout the Playcademy platform.
+ * It's exported as a singleton to ensure consistent communication across all parts
+ * of the application.
+ *
+ * **Why a Singleton?**:
+ * - Ensures all parts of the app use the same messaging instance
+ * - Prevents conflicts between multiple messaging systems
+ * - Simplifies the API - no need to pass instances around
+ * - Maintains consistent event listener management
+ *
+ * **Usage in Different Contexts**:
+ *
+ * **In Games**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Tell parent we're ready
+ * messaging.send(MessageEvents.READY, undefined)
+ *
+ * // Listen for pause/resume
+ * messaging.listen(MessageEvents.PAUSE, () => game.pause())
+ * messaging.listen(MessageEvents.RESUME, () => game.resume())
+ * ```
+ *
+ * **In Parent Shell**:
+ * ```typescript
+ * import { messaging, MessageEvents } from '@playcademy/sdk'
+ *
+ * // Send initialization data to game
+ * messaging.send(MessageEvents.INIT, { baseUrl, token, gameId })
+ *
+ * // Listen for game events
+ * messaging.listen(MessageEvents.EXIT, () => closeGame())
+ * messaging.listen(MessageEvents.READY, () => showGame())
+ * ```
+ *
+ * **Automatic Transport Selection**:
+ * The messaging system automatically chooses the right transport method:
+ * - Uses postMessage when game is in iframe sending to parent
+ * - Uses CustomEvent for local development and parent-to-game communication
+ *
+ * **Type Safety**:
+ * All message sending and receiving is fully type-safe with TypeScript.
+ */
+declare const messaging: PlaycademyMessaging;
 
 /**
  * Auto-initializes a PlaycademyClient with context from the environment.