@playcademy/sdk 0.16.1-beta.3 → 0.16.1-beta.5

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 import * as _playcademy_types from '@playcademy/types';
 import { GameManifest, LocalDayContext } from '@playcademy/types';
 export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
-import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig, TimebackGrade, TimebackSubject, HeartbeatRequest } from '@playcademy/types/timeback';
+import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig, TimebackGrade, TimebackSubject, ELevel, EndActivityRequest, HeartbeatRequest, EndActivityScoreData, EndActivityResponse } from '@playcademy/types/timeback';
+export { ELevel } from '@playcademy/types/timeback';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
 import { GamePermission, AUTH_PROVIDER_IDS } from '@playcademy/constants';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
@@ -30,6 +31,13 @@ interface RetryPolicy {
     retryDelaysMs?: readonly number[];
 }
 
+/**
+ * Base error class for Cademy SDK specific errors.
+ */
+declare class PlaycademyError extends Error {
+    constructor(message: string);
+}
+
 /**
  * @fileoverview Playcademy Messaging System
  *
@@ -158,11 +166,32 @@ declare enum MessageEvents {
      */
     DEMO_END = "PLAYCADEMY_DEMO_END",
     /**
-     * Game shares its latest TimeBack heartbeat window with the parent shell.
-     * The shell can relay this payload during top-level page teardown, which is
-     * more reliable than relying only on cross-origin iframe unload events.
+     * Game shares its latest TimeBack heartbeat window with the embedding
+     * window. The hub relays this payload during top-level page teardown
+     * (more reliable than cross-origin iframe unload events); in child mode
+     * this stream is the heartbeat's only delivery path.
      */
     TIMEBACK_HEARTBEAT_RELAY = "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY",
+    /**
+     * Game announces its tracker opened a run (startActivity).
+     * Today only child-mode games emit this: the parent opens its own
+     * Timeback run on receipt, so tracked time starts when the lesson
+     * does, not when the iframe boots.
+     */
+    TIMEBACK_ACTIVITY_START = "PLAYCADEMY_TIMEBACK_ACTIVITY_START",
+    /**
+     * Game relays its full end-activity report instead of POSTing it to
+     * its own backend. Today only child-mode games emit this: the parent
+     * reports the result to Timeback under its own identity.
+     */
+    TIMEBACK_ACTIVITY_END = "PLAYCADEMY_TIMEBACK_ACTIVITY_END",
+    /**
+     * Child game → parent game. An opaque checkpoint of the child's
+     * internal state, streamed during play so the parent always holds a
+     * near-current copy (the death-time postMessage hop is unreliable;
+     * continuous checkpointing is the design). Latest wins.
+     */
+    CHECKPOINT = "PLAYCADEMY_CHECKPOINT",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -1237,6 +1266,8 @@ declare abstract class PlaycademyBaseClient {
         isInIframe: boolean;
     };
     protected initPayload?: InitPayload;
+    /** Memoized `client.parent` handle; built on first access in child mode. */
+    private parentHandle?;
     protected launchId?: string;
     protected gameOrigin?: string;
     private browserTimeZone?;
@@ -1257,6 +1288,13 @@ declare abstract class PlaycademyBaseClient {
      * Local day context supplied by the platform during iframe initialization.
      */
     get localDay(): LocalDayContext | undefined;
+    /**
+     * Null outside `mode: 'child'` even if a payload smuggled in a `parent`
+     * block, so `if (client.parent)` is a reliable child-mode test. The
+     * returned handle is the wire block plus `checkpoint()`, memoized so
+     * `client.parent === client.parent`.
+     */
+    get parent(): ParentGameHandle | null;
     /**
      * Sets the authentication token for API requests.
      */
@@ -1403,153 +1441,14 @@ declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(thi
 declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
 
 /**
- * Playcademy SDK client for game developers.
- * Provides namespaced access to platform features for games running inside Cademy.
+ * `endActivity()`'s resolution in child mode: the report was relayed to the
+ * parent game rather than POSTed to the platform, so no platform award data
+ * (courseId, xpAwarded) exists. The parent reports under its own identity.
  */
-declare class PlaycademyClient extends PlaycademyBaseClient {
-    /**
-     * Connect external identity providers to the user's Playcademy account.
-     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
-     */
-    identity: {
-        connect: (options: AuthOptions) => Promise<AuthResult>;
-        _getContext: () => {
-            isInIframe: boolean;
-        };
-    };
-    /**
-     * Game runtime lifecycle and asset loading.
-     * - `exit()` - Return to Cademy hub
-     * - `getGameToken()` - Get short-lived auth token
-     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
-     * - `on('pause')`, `on('resume')` - Handle visibility changes
-     */
-    runtime: {
-        exit: () => void;
-        onInit: (handler: (context: GameContextPayload) => void) => void;
-        onTokenRefresh: (handler: (data: {
-            token: string;
-            exp: number;
-        }) => void) => void;
-        onPause: (handler: () => void) => void;
-        onResume: (handler: () => void) => void;
-        onForceExit: (handler: () => void) => void;
-        onOverlay: (handler: (isVisible: boolean) => void) => void;
-        ready: () => void;
-        sendTelemetry: (data: {
-            fps: number;
-            mem: number;
-        }) => void;
-        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
-            token: string;
-            exp: number;
-        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
-        removeAllListeners: () => void;
-        getListenerCounts: () => Record<string, number>;
-        assets: {
-            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit) => Promise<Response>;
-            json: <T = unknown>(path: string) => Promise<T>;
-            blob: (path: string) => Promise<Blob>;
-            text: (path: string) => Promise<string>;
-            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
-        };
-    };
-    /**
-     * TimeBack integration for activity tracking and user context.
-     *
-     * User context (cached from init, refreshable):
-     * - `user.role` - User's role (student, parent, teacher, etc.)
-     * - `user.enrollments` - Courses the player is enrolled in for this game
-     * - `user.refresh({ only: ['enrollments'] })` - Refresh enrollments from server
-     * - `user.organizations` - Schools/districts the player belongs to
-     * - `user.fetch()` - Refresh user context from server
-     *
-     * Activity tracking:
-     * - `currentRunId` - Current activity run ID, or undefined when inactive
-     * - `startActivity(metadata)` - Begin tracking an activity, return its run
-     *   ID, and automatically handle hidden-tab and visible-tab inactivity
-     *   with configurable paused-heartbeat timeout behavior
-     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
-     * - `endActivity(scoreData)` - Submit activity results to TimeBack
-     */
-    timeback: {
-        assessments: {
-            start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
-            latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
-            get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
-            save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
-            submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;
-        };
-        readonly user: TimebackUser;
-        readonly currentRunId: string | undefined;
-        startActivity: (metadata: _playcademy_types.ActivityData, options?: StartActivityOptions) => StartActivityResult;
-        pauseActivity: () => void;
-        resumeActivity: () => void;
-        endActivity: (data: _playcademy_types.EndActivityScoreData) => Promise<_playcademy_types.EndActivityResponse>;
-        course: {
-            advance: (options?: {
-                subject?: _playcademy_types.TimebackSubject;
-            }) => Promise<_playcademy_types.AdvanceCourseResponse>;
-            unenroll: (options?: {
-                subject?: _playcademy_types.TimebackSubject;
-                force?: boolean;
-            }) => Promise<_playcademy_types.UnenrollCourseResponse>;
-        };
-    };
-    /**
-     * Game score submission and leaderboards.
-     * - `submit(score, metadata?)` - Record a game score
-     */
-    scores: {
-        submit: (score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
-    };
-    /**
-     * Read-only leaderboard access for the current game scope.
-     * - `fetch(options?)` - Fetch leaderboard entries
-     */
-    leaderboard: {
-        fetch: (options?: _playcademy_types.LeaderboardOptions) => Promise<_playcademy_types.GameLeaderboardEntry[]>;
-    };
-    /**
-     * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
-     * so callers should gate on the mode before reaching in.
-     * - `profile.get()` - Read the anonymous demo player's profile
-     * - `profile.update(updates)` - Update the demo player's profile (today: the required `displayName`)
-     * - `end(score, options?)` - Signal to the parent shell that the demo has ended
-     */
-    demo: {
-        profile: {
-            get: () => Promise<_playcademy_types.DemoProfile>;
-            update: (updates: _playcademy_types.DemoProfileUpdate) => Promise<_playcademy_types.DemoProfile>;
-        };
-        end: (score: number, options?: DemoEndOptions) => void;
-    };
-    /**
-     * Make requests to your game's custom backend API routes.
-     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
-     * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
-     */
-    backend: {
-        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
-        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-    };
-    /** Auto-initializes a PlaycademyClient with context from the environment */
-    static init: typeof init;
-    /** Authenticates a user with email and password */
-    static login: typeof login;
-    /** Static identity utilities for OAuth operations */
-    static identity: {
-        parseOAuthState: typeof parseOAuthState;
-    };
+interface RelayedEndActivityResult {
+    status: 'relayed';
+    runId: string;
 }
-
 /**
  * Options for configuring activity tracking behavior.
  */
@@ -1887,8 +1786,79 @@ type TokenType = 'session' | 'apiKey' | 'gameJwt';
  * - `'standalone'` — game is running outside any iframe (e.g. `bun run dev`
  *   or direct-deploy preview) with a mock token and no real platform
  *   context. API calls will not succeed; use this to branch UX locally.
+ * - `'child'` — game is embedded by another game (the parent), which ran
+ *   the INIT handshake itself and included a `parent` block in the payload.
+ *   The user and token are real (the parent's own). Direct Timeback
+ *   reporting is suppressed and relayed to the parent instead; read
+ *   `client.parent` for the parent's identity and launch instructions.
  */
-type PlaycademyMode = 'platform' | 'demo' | 'standalone';
+type PlaycademyMode = 'platform' | 'demo' | 'standalone' | 'child';
+/**
+ * What a parent game asks a child game to deliver.
+ *
+ * This contract is platform-defined so any parent can launch any child
+ * without pair-specific vocabularies. `lessonId` addresses the child's own
+ * catalog; the child maps it to internal content. Pair-specific extras
+ * belong in `extensions`, which the platform never interprets (the same
+ * split LTI makes between its resource link and custom claims).
+ *
+ * Parent and child ship independently, so children should still validate
+ * the intent at runtime; SDK compatibility floors manage version skew.
+ */
+interface LaunchIntent {
+    /** The activity to deliver, addressed in the child's own catalog. */
+    lessonId: string;
+    /** Pedagogy stage of the lesson (the platform's E1-E4 taxonomy). */
+    eLevel: ELevel;
+    /** Pair-specific extras. Never interpreted by the platform. */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * What `client.parent` actually returns: the parent's wire context plus
+ * the child's one capability toward it. The wire block
+ * (`ParentGameContext`) stays a pure serializable payload; this handle
+ * wraps it. Null outside child mode, so `if (client.parent)` remains the
+ * child-launch test.
+ */
+type ParentGameHandle = ParentGameContext & {
+    /**
+     * Streams an opaque checkpoint of this game's state to the parent,
+     * so an interrupted launch can resume later (the parent hands it
+     * back as `client.parent.resume`). Call it whenever your state
+     * meaningfully changes — never wait for teardown, the closing-tab
+     * message hop is unreliable. State must be JSON-serializable and
+     * under 64KB; anything else is dropped with a warning. This is not
+     * your save system: the parent holds it for resume only.
+     */
+    checkpoint(state: unknown): void;
+};
+/**
+ * The parent game's block in a `mode: 'child'` INIT payload. Present only
+ * when a parent game launched this client (see the parent-child game
+ * embedding proposal, `docs/dev/timeback/`).
+ */
+interface ParentGameContext {
+    /** The parent game's own platform game ID (NOT this game's ID). */
+    gameId: string;
+    /** What the parent wants this child to deliver. */
+    intent: LaunchIntent;
+    /**
+     * An earlier launch's checkpoint state, when the parent is resuming
+     * an interrupted lesson. Opaque: this game wrote it via
+     * `client.parent.checkpoint()`, and only this game can interpret it.
+     * Validate it like the intent — a blob from an older build of this
+     * game should be ignored, not trusted.
+     */
+    resume?: unknown;
+    /**
+     * The interrupted run id, present when the parent is resuming a
+     * lesson. Consumed by the SDK: the launch's first `startActivity()`
+     * adopts it automatically, which is what continues the platform run.
+     * Games never read this; pass an explicit `runId` to
+     * `startActivity()` to start a deliberate fresh attempt instead.
+     */
+    resumeRunId?: string;
+}
 interface ClientConfig {
     baseUrl: string;
     gameUrl?: string;
@@ -1917,6 +1887,8 @@ interface InitPayload {
     launchId?: string;
     /** When `true`, the parent shell provides a heartbeat relay via postMessage, so the SDK can skip its own `fetch({ keepalive })` beacon on pagehide. Defaults to `false`. */
     hasHeartbeatRelay?: boolean;
+    /** Parent game context. Present only when `mode` is `'child'`. */
+    parent?: ParentGameContext;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -1951,6 +1923,163 @@ interface ClientEvents {
     };
 }
 
+/**
+ * Playcademy SDK client for game developers.
+ * Provides namespaced access to platform features for games running inside Cademy.
+ */
+declare class PlaycademyClient extends PlaycademyBaseClient {
+    /**
+     * Connect external identity providers to the user's Playcademy account.
+     * - `connect(provider)` - Link Discord, Google, etc. via OAuth popup
+     */
+    identity: {
+        connect: (options: AuthOptions) => Promise<AuthResult>;
+        _getContext: () => {
+            isInIframe: boolean;
+        };
+    };
+    /**
+     * Game runtime lifecycle and asset loading.
+     * - `exit()` - Return to Cademy hub
+     * - `getGameToken()` - Get short-lived auth token
+     * - `assets.url()`, `assets.json()`, `assets.fetch()` - Load game assets
+     * - `on('pause')`, `on('resume')` - Handle visibility changes
+     */
+    runtime: {
+        exit: () => void;
+        onInit: (handler: (context: GameContextPayload) => void) => void;
+        onTokenRefresh: (handler: (data: {
+            token: string;
+            exp: number;
+        }) => void) => void;
+        onPause: (handler: () => void) => void;
+        onResume: (handler: () => void) => void;
+        onForceExit: (handler: () => void) => void;
+        onOverlay: (handler: (isVisible: boolean) => void) => void;
+        ready: () => void;
+        sendTelemetry: (data: {
+            fps: number;
+            mem: number;
+        }) => void;
+        removeListener: (eventType: MessageEvents, handler: ((context: GameContextPayload) => void) | ((data: {
+            token: string;
+            exp: number;
+        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
+        removeAllListeners: () => void;
+        getListenerCounts: () => Record<string, number>;
+        assets: {
+            url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+            fetch: (path: string, options?: RequestInit) => Promise<Response>;
+            json: <T = unknown>(path: string) => Promise<T>;
+            blob: (path: string) => Promise<Blob>;
+            text: (path: string) => Promise<string>;
+            arrayBuffer: (path: string) => Promise<ArrayBuffer>;
+        };
+    };
+    /**
+     * TimeBack integration for activity tracking and user context.
+     *
+     * User context (cached from init, refreshable):
+     * - `user.role` - User's role (student, parent, teacher, etc.)
+     * - `user.enrollments` - Courses the player is enrolled in for this game
+     * - `user.refresh({ only: ['enrollments'] })` - Refresh enrollments from server
+     * - `user.organizations` - Schools/districts the player belongs to
+     * - `user.fetch()` - Refresh user context from server
+     *
+     * Activity tracking:
+     * - `currentRunId` - Current activity run ID, or undefined when inactive
+     * - `startActivity(metadata)` - Begin tracking an activity, return its run
+     *   ID, and automatically handle hidden-tab and visible-tab inactivity
+     *   with configurable paused-heartbeat timeout behavior
+     * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
+     * - `endActivity(scoreData)` - Submit activity results to TimeBack
+     */
+    timeback: {
+        assessments: {
+            start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
+            get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
+            submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;
+        };
+        readonly user: TimebackUser;
+        readonly currentRunId: string | undefined;
+        startActivity: (metadata: _playcademy_types.ActivityData, options?: StartActivityOptions) => StartActivityResult;
+        pauseActivity: () => void;
+        resumeActivity: () => void;
+        endActivity: (data: _playcademy_types.EndActivityScoreData) => Promise<_playcademy_types.EndActivityResponse | RelayedEndActivityResult>;
+        course: {
+            advance: (options?: {
+                subject?: _playcademy_types.TimebackSubject;
+            }) => Promise<_playcademy_types.AdvanceCourseResponse>;
+            unenroll: (options?: {
+                subject?: _playcademy_types.TimebackSubject;
+                force?: boolean;
+            }) => Promise<_playcademy_types.UnenrollCourseResponse>;
+        };
+    };
+    /**
+     * Game score submission and leaderboards.
+     * - `submit(score, metadata?)` - Record a game score
+     */
+    scores: {
+        submit: (score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
+    };
+    /**
+     * Read-only leaderboard access for the current game scope.
+     * - `fetch(options?)` - Fetch leaderboard entries
+     */
+    leaderboard: {
+        fetch: (options?: _playcademy_types.LeaderboardOptions) => Promise<_playcademy_types.GameLeaderboardEntry[]>;
+    };
+    /**
+     * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
+     * so callers should gate on the mode before reaching in.
+     * - `profile.get()` - Read the anonymous demo player's profile
+     * - `profile.update(updates)` - Update the demo player's profile (today: the required `displayName`)
+     * - `end(score, options?)` - Signal to the parent shell that the demo has ended
+     */
+    demo: {
+        profile: {
+            get: () => Promise<_playcademy_types.DemoProfile>;
+            update: (updates: _playcademy_types.DemoProfileUpdate) => Promise<_playcademy_types.DemoProfile>;
+        };
+        end: (score: number, options?: DemoEndOptions) => void;
+    };
+    /**
+     * Make requests to your game's custom backend API routes.
+     * - `get(path)`, `post(path, body)`, `put()`, `delete()` - HTTP methods
+     * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
+     */
+    backend: {
+        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
+        url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
+    };
+    /**
+     * Launch other Playcademy games as embedded children (platform mode only).
+     * - `launch({ slug, container, intent })` - Mount a child game in a nested
+     *   iframe with `mode: 'child'`; returns a session handle with `finished`
+     *   and `closed` promises and `close()`
+     */
+    embed: {
+        launch(options: EmbedLaunchOptions): EmbedSession;
+    };
+    /** Auto-initializes a PlaycademyClient with context from the environment */
+    static init: typeof init;
+    /** Authenticates a user with email and password */
+    static login: typeof login;
+    /** Static identity utilities for OAuth operations */
+    static identity: {
+        parseOAuthState: typeof parseOAuthState;
+    };
+}
+
 /**
  * Event and message payload types for SDK messaging system
  */
@@ -2059,6 +2188,42 @@ interface DemoEndPayload extends DemoEndOptions {
 }
 type TimebackHeartbeatRelayRequest = Omit<HeartbeatRequest, 'gameId' | 'studentId' | 'windowStartedAtMs' | 'windowSequence'> & {
     windowStartedAtMs: number;
+    /**
+     * Marks a closed heartbeat window from the child's 15s accounting
+     * cadence: the window's totals are final, its key never recurs, and
+     * the parent forwards it exactly once (retries are safe against the
+     * server's first-write-wins window dedupe). Absent on the 1s display
+     * snapshots of the still-open window.
+     */
+    windowClosed?: boolean;
+};
+/**
+ * Wire payload for `PLAYCADEMY_CHECKPOINT`. An opaque snapshot of the
+ * child game's internal state; the SDK and the parent never interpret
+ * `state`. The parent stamps the resume envelope's `childRunId` from the
+ * activity-start announcement, so the checkpoint itself carries no ids.
+ */
+interface ChildCheckpointRelay {
+    state: unknown;
+}
+/**
+ * Wire payload for `PLAYCADEMY_TIMEBACK_ACTIVITY_START`. A child-mode game
+ * announces that its tracker opened a run, so the parent can open its own
+ * Timeback run at the moment the lesson actually begins.
+ */
+type TimebackActivityStartRelay = Pick<TimebackHeartbeatRelayRequest, 'runId' | 'resumeId' | 'activityData'>;
+/**
+ * Wire payload for `PLAYCADEMY_TIMEBACK_ACTIVITY_END`. The same end-activity
+ * body a platform-mode game would POST to its backend, relayed to the parent
+ * instead. `timingData.durationSeconds` is the full active sitting and
+ * `sessionTimingData` carries the FULL session totals: a relayed window is
+ * never marked persisted (a postMessage hand-off proves nothing about the
+ * parent's POST), so the parent reconciles these totals against the windows
+ * the server confirmed before reporting the completion's remainder.
+ */
+type TimebackActivityEndRelay = Omit<EndActivityRequest, 'gameId' | 'studentId' | 'xpEarned'> & {
+    /** The child's XP suggestion; the parent decides the actual award. */
+    xpEarned?: number;
 };
 
 /**
@@ -2073,6 +2238,243 @@ interface GameTokenResponse {
     baseUrl?: string;
 }
 
+/**
+ * Public types for the launch protocol's parent side: the embedded
+ * child-game session behind `client.embed.launch()`. Only what `launch()`
+ * callers touch lives here; the implementation and its constructor-side
+ * plumbing contracts live in `core/launch/session.ts`.
+ */
+
+/**
+ * How a child launch is recorded on this game's Timeback course.
+ * The same metadata you would give `startActivity()` if your own document
+ * were running the lesson: the embed session runs the whole
+ * start-through-end lifecycle for you, stamped with this.
+ */
+interface EmbedTimebackRecording {
+    /** The activity on this game's own course the launch is recorded as. */
+    activityId: string;
+    /** Display name for dashboards; prettified from `activityId` when omitted. */
+    activityName?: string;
+    /** With `subject`, routes the recording to one of this game's courses. */
+    grade: TimebackGrade;
+    /** With `grade`, routes the recording to one of this game's courses. */
+    subject: TimebackSubject;
+    /** Course id hint, same semantics as `startActivity()`. */
+    courseId?: string;
+}
+/**
+ * Everything a parent needs to resume an interrupted launch later. The
+ * parent persists this wherever the interruption demands (memory for
+ * exit-and-return, localStorage for tab close, its backend KV for
+ * cross-device) and hands it back via `embed.launch({ resume })`.
+ */
+interface EmbedResumeEnvelope {
+    /**
+     * The child's opaque checkpoint state, exactly as it last reported
+     * it. Never introspect it: only the child can interpret its own
+     * state, and it validates the blob on the way back in.
+     */
+    state: unknown;
+    /**
+     * The child's own run id from the interrupted launch, when a run was
+     * active. On resume it crosses to the child, whose SDK re-announces
+     * it automatically at the next launch's first start; the announced match
+     * is what makes reusing `parentRunId` safe.
+     */
+    childRunId?: string;
+    /**
+     * The interrupted platform run, when Timeback reporting was active.
+     * Reused (with a fresh sitting id) only when the child accepts the
+     * resume; otherwise a fresh run is minted.
+     */
+    parentRunId?: string;
+}
+/**
+ * Custom persistence for resume envelopes, passed as `launch()`'s
+ * `resume` option. The default (when `resume` is omitted) is a built-in
+ * localStorage store keyed by user, parent game, child game, and the
+ * intent's lesson identity; supply your own store to keep envelopes
+ * elsewhere (for example your backend, for cross-device resume).
+ */
+interface EmbedResumeStore {
+    /**
+     * Returns the stored envelope for this lesson identity, or
+     * null/undefined when there is nothing to resume. May be async; the
+     * boot waits for it before the child's INIT is sent.
+     */
+    load(): EmbedResumeEnvelope | null | undefined | Promise<EmbedResumeEnvelope | null | undefined>;
+    /**
+     * Persists the latest envelope. Called on every checkpoint the child
+     * relays (envelopes are capped at 64KB) and again when run identity
+     * is minted. Writes should be synchronous or fire-and-forget: the
+     * SDK never blocks on them, and a throw costs that envelope's
+     * persistence, never the launch. Returned promises are used only for
+     * ordering: `save` and `clear` run strictly in call order, so a slow
+     * async save cannot land after the completion's clear.
+     */
+    save(envelope: EmbedResumeEnvelope): void;
+    /** Deletes the stored envelope. Called once when the launch completes. */
+    clear(): void;
+}
+/**
+ * Play-time totals for a child launch, measured by the child's own
+ * tracker (the parent's document is idle while the student plays).
+ */
+interface EmbedSessionTiming {
+    /** Seconds of active play. */
+    activeSeconds: number;
+    /** Seconds the child's tracker classified as paused or inactive, when known. */
+    inactiveSeconds?: number;
+}
+/**
+ * The launch's activity record, resolved by `session.finished`.
+ *
+ * `'completed'` carries the child's report and the `end()` capability;
+ * `'abandoned'` means the session ended first (child exit or `close()`);
+ * `'failed'` means the launch never happened. Failure is a state to
+ * render, not an exception to catch — `finished` never rejects.
+ */
+type EmbedActivity = EmbedActivityCompleted | EmbedActivityAbandoned | EmbedActivityFailed;
+/** The child called `endActivity()` and its report was relayed. */
+interface EmbedActivityCompleted {
+    status: 'completed';
+    /** Correct answers, from the child's report. */
+    correct: number;
+    /** Total questions, from the child's report. */
+    total: number;
+    timing: EmbedSessionTiming;
+    /**
+     * The child's full relayed end-activity body: its own activity ids,
+     * suggested XP, and extensions. Audit data — the parent decides what
+     * actually reaches the platform, via `end()`.
+     */
+    childReport: TimebackActivityEndRelay;
+    /**
+     * Posts the launch's completion to the parent's own backend: the
+     * parent-minted run id, the `timeback` recording, the caller's score
+     * and XP decision, and the child's ids as audit extensions. Requires
+     * the `timeback` option at launch. Calling twice returns the same
+     * promise, so a launch can never double-report from the client.
+     */
+    end(scores: EndActivityScoreData): Promise<EndActivityResponse>;
+}
+/**
+ * The session ended (child exit or `close()`) before a report arrived.
+ * Played time has already reached the platform through forwarded
+ * heartbeats; an abandoned launch leaves no completion, exactly like a
+ * student wandering away from any other game.
+ */
+interface EmbedActivityAbandoned {
+    status: 'abandoned';
+    timing: EmbedSessionTiming;
+    /**
+     * The final resume envelope, when the child checkpointed during the
+     * launch. Persist it (see `EmbedResumeEnvelope`) and pass it back to
+     * `embed.launch({ resume })` to pick the lesson up later. Absent
+     * when the child never checkpointed.
+     */
+    resume?: EmbedResumeEnvelope;
+}
+/** The launch never happened: the child could not be resolved or booted. */
+interface EmbedActivityFailed {
+    status: 'failed';
+    /** Why — unknown slug, missing deployment URL, INIT error or timeout. */
+    error: PlaycademyError;
+}
+/**
+ * Handle for one embedded child-game session.
+ */
+interface EmbedSession {
+    /** The mounted child iframe. Useful for focus management. */
+    readonly iframe: HTMLIFrameElement;
+    /**
+     * The latest resume envelope, live during play; null until the child
+     * first checkpoints. Read it on your own cadence to persist
+     * mid-lesson (for example a debounced upload to your backend), so a
+     * closed tab can resume on another device.
+     */
+    readonly checkpoint: EmbedResumeEnvelope | null;
+    /**
+     * Resolves the launch's activity record when it ends — the
+     * `animation.finished` idiom. Never rejects: operational failures
+     * resolve as `{ status: 'failed', error }`.
+     */
+    readonly finished: Promise<EmbedActivity>;
+    /**
+     * Resolves when the session is torn down and the iframe is unmounted:
+     * on child exit, `close()`, boot failure, or when the SDK detects the
+     * iframe was removed from the DOM. `finished` can resolve earlier than
+     * this (a completed child usually shows a results screen before
+     * exiting), so use `closed` to dismiss surrounding UI.
+     */
+    readonly closed: Promise<void>;
+    /**
+     * Tears the session down: unmounts the iframe and stops all listeners.
+     * Resolves a still-pending `finished` as `'abandoned'`. Safe to call
+     * more than once. Calling it is the deterministic path; the SDK also
+     * tears down when the child exits, and detects an iframe removed
+     * without `close()` within ~5 seconds, so nothing leaks either way.
+     */
+    close(): void;
+}
+
+/**
+ * Options for `client.embed.launch()`.
+ */
+interface EmbedLaunchOptions {
+    /** Slug of the child game to launch. Resolved to a game id at launch time. */
+    slug: string;
+    /** Element the child iframe is mounted into. The iframe fills it. */
+    container: HTMLElement;
+    /**
+     * What the child should deliver. This is the platform-defined
+     * {@link LaunchIntent} contract; it crosses the iframe in the INIT
+     * payload's `parent` block and surfaces in the child as `client.parent.intent`.
+     */
+    intent: LaunchIntent;
+    /**
+     * Whether and how an interrupted launch can resume.
+     *
+     * Omitted (the default): the SDK persists the child's latest
+     * checkpoint in localStorage, keyed by user, this game, the child,
+     * and the intent's lesson identity. The next launch with the same
+     * identity resumes automatically; completion clears the entry. Inert
+     * for children that never call `client.parent.checkpoint()`.
+     *
+     * `false`: no persistence and no automatic resume. The manual surface
+     * (`session.checkpoint`, the abandoned outcome's `resume`) still works.
+     *
+     * An {@link EmbedResumeEnvelope}: fully manual, one-shot. The launch
+     * resumes from exactly this envelope and nothing is persisted.
+     *
+     * An {@link EmbedResumeStore}: delegate persistence (for example to
+     * your backend, for cross-device resume).
+     *
+     * Whatever the policy, the child receives only the opaque `state`
+     * (as `client.parent.resume`) and decides whether to use it; run ids
+     * stay parent-side and drive run continuity when the child accepts.
+     */
+    resume?: false | EmbedResumeEnvelope | EmbedResumeStore;
+    /**
+     * Records the launch on this game's Timeback course: the metadata
+     * you would have given `startActivity()` if your own document were
+     * running the lesson. Stays in the parent SDK, stamping every
+     * forwarded heartbeat and the final completion; it never crosses the
+     * iframe. Omit for a pure UX embed.
+     */
+    timeback?: EmbedTimebackRecording;
+    /**
+     * Overrides the child's resolved deployment URL. Intended for local
+     * development, where the child runs on a dev server the platform
+     * doesn't know about. With `gameUrl` set, a slug that fails to
+     * resolve degrades to a warning (the slug stands in as the child's
+     * game id) instead of failing the launch, so an unregistered child
+     * still launches locally.
+     */
+    gameUrl?: string;
+}
+
 /**
  * Scores namespace types
  */
@@ -2269,4 +2671,4 @@ interface PlatformTimebackUser extends PlatformTimebackUserContext {
 }
 
 export { PlaycademyClient };
-export type { AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LoginResponse, MasteryResponse, ParentGameContext, ParentGameHandle, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };