@playcademy/sdk 0.16.1-beta.2 → 0.16.1-beta.21

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _playcademy_types from '@playcademy/types';
 import { LocalDayContext } from '@playcademy/types';
-import { TimebackGrade, TimebackSubject, HeartbeatRequest } from '@playcademy/types/timeback';
+import { TimebackGrade, TimebackSubject, ELevel, ChildEndActivityScoreData, EndActivityRequest, HeartbeatRequest, EndActivityScoreData, EndActivityResponse } from '@playcademy/types/timeback';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
@@ -227,6 +227,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?;
@@ -247,6 +249,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.
      */
@@ -520,11 +529,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.
@@ -594,11 +624,36 @@ interface MessageEventMap {
     [MessageEvents.DEMO_END]: DemoEndPayload;
     /** Latest TimeBack heartbeat window for parent-shell unload relay */
     [MessageEvents.TIMEBACK_HEARTBEAT_RELAY]: TimebackHeartbeatRelayRequest;
+    /** Child-mode run-opened announcement */
+    [MessageEvents.TIMEBACK_ACTIVITY_START]: TimebackActivityStartRelay;
+    /** Child-mode end-activity report relay */
+    [MessageEvents.TIMEBACK_ACTIVITY_END]: TimebackActivityEndRelay;
+    [MessageEvents.CHECKPOINT]: ChildCheckpointRelay;
     /** Authentication state change notification */
     [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
     /** OAuth callback data from popup/new-tab windows */
     [MessageEvents.AUTH_CALLBACK]: AuthCallbackPayload;
 }
+/**
+ * Options for `messaging.listen()`.
+ */
+interface ListenOptions {
+    /**
+     * Accept postMessages only from the embedding window (`window.parent`).
+     *
+     * Defaults by direction: on for launcher-directed control messages
+     * (see the direction table), off otherwise. A child iframe posts to
+     * this window too (that is how the embed relay works), but it must
+     * never be able to impersonate the platform above; pass `false` to
+     * loosen a launcher-directed listener deliberately (for example a
+     * test rig that posts control messages from a non-parent window).
+     * Local CustomEvent delivery is unaffected, since a separate
+     * document cannot dispatch into this one. At the top window nothing
+     * can match (`window.parent === window`), which is correct: a
+     * standalone run has no launcher.
+     */
+    fromParent?: boolean;
+}
 /**
  * **PlaycademyMessaging Class**
  *
@@ -734,7 +789,7 @@ declare class PlaycademyMessaging {
      * })
      * ```
      */
-    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>): void;
+    listen<K extends MessageEvents>(type: K, handler: MessageHandler<MessageEventMap[K]>, options?: ListenOptions): void;
     /**
      * **Remove Message Listener Method**
      *
@@ -966,153 +1021,14 @@ declare class PlaycademyMessaging {
 declare const messaging: PlaycademyMessaging;
 
 /**
- * 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.
  */
@@ -1450,8 +1366,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' | '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.
  */
-type PlaycademyMode = 'platform' | 'demo' | 'standalone';
+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;
@@ -1480,6 +1467,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;
 }
 interface GameContextPayload extends InitPayload {
     forwardKeys?: string[];
@@ -1493,6 +1482,202 @@ 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>;
+            stop: (attemptId: string) => Promise<{
+                attemptId: string;
+            }>;
+            save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
+            submitItem: (attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
+            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;
+    };
+}
+/**
+ * A game client narrowed to a child launch (`mode: 'child'`).
+ *
+ * Produced by `isChildLaunched()`. Three members sharpen: `mode` becomes
+ * the literal `'child'`, `parent` is non-null, and
+ * `timeback.endActivity()` gains a relaxed call signature where
+ * `xpAwarded` is optional and the result is always the relayed shape.
+ * Built as an intersection so the class's private state stays assignable;
+ * the relaxed signature joins the base one as an overload, which is why
+ * an un-narrowed client still requires `xpAwarded`.
+ */
+type ChildLaunchedClient = PlaycademyClient & {
+    mode: 'child';
+    parent: ParentGameHandle;
+    timeback: {
+        endActivity(data: ChildEndActivityScoreData): Promise<RelayedEndActivityResult>;
+    };
+};
+/**
+ * Narrows a client to `ChildLaunchedClient` when a parent game launched
+ * it. TypeScript cannot condition a signature on a runtime mode, but it
+ * can flow this narrowing: inside the guarded branch, `client.parent` is
+ * non-null and `endActivity()` may omit `xpAwarded` (the parent game
+ * decides the award).
+ *
+ * @example
+ * ```typescript
+ * if (isChildLaunched(client)) {
+ *     const { lessonId, eLevel } = client.parent.intent
+ *     // ... play the lesson ...
+ *     await client.timeback.endActivity({ correctQuestions, totalQuestions })
+ * }
+ * ```
+ */
+declare function isChildLaunched(client: PlaycademyClient): client is ChildLaunchedClient;
+
 /**
  * Event and message payload types for SDK messaging system
  */
@@ -1583,6 +1768,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;
 };
 
 /**
@@ -1592,6 +1813,265 @@ interface LoginResponse {
     token: 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';
+    /**
+     * The platform run this completion records under. One run ends in at
+     * most one completion (the server dedupes on it), and a resumed launch
+     * keeps the interrupted run's id — so this doubles as the completion's
+     * attempt identity: feed it to whatever consumes the result and drop
+     * anything you have seen before. Absent only for pure UX embeds
+     * (launched without `timeback`), which record nothing.
+     */
+    runId?: string;
+    /** 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';
+    /**
+     * The platform run the launch was recording under, when one had
+     * opened. Absent when the child never started an activity or the
+     * launch was a pure UX embed.
+     */
+    runId?: string;
+    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 platform run this launch records under, or null before the run
+     * opens (the child's first activity) and for pure UX embeds. Stable
+     * once set; also echoed on the finished record, which is where most
+     * callers should read it.
+     */
+    readonly runId: string | null;
+    /**
+     * 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
  */
@@ -1672,5 +2152,5 @@ interface DevUploadHooks {
     onClose?: () => void;
 }
 
-export { ApiError, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, DevUploadEvent, DevUploadHooks, ErrorResponseBody, PlaycademyMode };
+export { ApiError, MessageEvents, PlaycademyClient, PlaycademyError, extractApiErrorInfo, isChildLaunched, messaging };
+export type { ApiErrorCode, ApiErrorInfo, ChildLaunchedClient, DevUploadEvent, DevUploadHooks, ErrorResponseBody, PlaycademyMode };