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

package/dist/internal.d.ts

@@ -1,5 +1,7 @@
 import { SchemaInfo } from '@playcademy/cloudflare';
-import { TimebackGrade, TimebackSubject, HeartbeatRequest, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
+import { GamePermission, AUTH_PROVIDER_IDS } from '@playcademy/constants';
+import { TimebackGrade, TimebackSubject, ELevel, HeartbeatRequest, EndActivityRequest, EndActivityScoreData, EndActivityResponse, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
+export { AssessmentAttemptSnapshot, AssessmentFlow, AssessmentItemSubmission, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ELevel, PlayableAssessment, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, StartAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult } from '@playcademy/types/timeback';
 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';
@@ -7,7 +9,6 @@ import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { DomainValidationRecords } from '@playcademy/types/game';
 import { z } from 'zod';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
-import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
 /** Permitted HTTP verbs */
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -292,11 +293,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.
@@ -366,11 +388,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**
  *
@@ -506,7 +553,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**
      *
@@ -736,6 +783,22 @@ declare class PlaycademyMessaging {
  * All message sending and receiving is fully type-safe with TypeScript.
  */
 declare const messaging: PlaycademyMessaging;
+/**
+ * Validates that a `message` event came from an embedded game iframe this
+ * window controls. This is a security boundary — every receiver that
+ * accepts game→embedder messages should gate on it:
+ *
+ * - `source` must be the iframe's own `contentWindow` (no other window may
+ *   drive the session)
+ * - `'null'` (sandboxed, opaque) origins are rejected
+ * - unless `origin` is the `'*'` wildcard, the event origin must match it
+ *   exactly
+ *
+ * `messaging.listen()` is the wrong tool for that direction: it accepts
+ * messages arriving at this window without source filtering, which is
+ * correct only for a game receiving from its own embedder.
+ */
+declare function isTrustedIframeMessage(event: MessageEvent, iframeWindow: Window | null, origin: string): boolean;
 
 /**
  * @fileoverview Authentication Strategy Pattern
@@ -1005,6 +1068,8 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
 interface GameMetadata {
     description?: string;
     emoji?: string;
+    /** Browser permissions delegated to the game's iframe (opt-in per game). */
+    permissions?: GamePermission[];
     [key: string]: unknown;
 }
 /**
@@ -1990,6 +2055,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?;
@@ -2010,6 +2077,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.
      */
@@ -2155,21 +2229,6 @@ declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(thi
  */
 declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
 
-/**
- * Cache configuration types for runtime customization
- */
-/**
- * Runtime configuration for TTL cache behavior
- */
-interface TTLCacheConfig {
-    /** Time-to-live in milliseconds. Set to 0 to disable caching for this call. */
-    ttl?: number;
-    /** Force refresh, bypassing cache */
-    force?: boolean;
-    /** Skip cache and fetch fresh data (alias for force) */
-    skipCache?: boolean;
-}
-
 /**
  * Options for configuring activity tracking behavior.
  */
@@ -2227,6 +2286,21 @@ interface StartActivityResult {
     runId: string;
 }
 
+/**
+ * Cache configuration types for runtime customization
+ */
+/**
+ * Runtime configuration for TTL cache behavior
+ */
+interface TTLCacheConfig {
+    /** Time-to-live in milliseconds. Set to 0 to disable caching for this call. */
+    ttl?: number;
+    /** Force refresh, bypassing cache */
+    force?: boolean;
+    /** Skip cache and fetch fresh data (alias for force) */
+    skipCache?: boolean;
+}
+
 /**
  * Type definitions for the game timeback namespace.
  *
@@ -2507,8 +2581,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;
@@ -2537,6 +2682,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
@@ -2679,6 +2826,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;
 };
 
 /**
@@ -2693,6 +2876,265 @@ 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';
+    /**
+     * 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
  */
@@ -2796,6 +3238,29 @@ interface BucketFile {
     lastModified: string;
     contentType?: string;
 }
+/**
+ * Options for a single-page bucket listing
+ */
+interface BucketListPageOptions {
+    /** Restrict results to keys starting with this prefix */
+    prefix?: string;
+    /** Opaque continuation cursor from the previous page's result */
+    cursor?: string;
+    /** Page size (1-1000); the server may return fewer */
+    limit?: number;
+    /** Roll deeper keys into `prefixes` entries, S3 delimiter style */
+    delimiter?: string;
+}
+/**
+ * One page of a bucket listing
+ */
+interface BucketFilePage {
+    files: BucketFile[];
+    /** Rolled-up common prefixes; present for delimiter listings that found any */
+    prefixes?: string[];
+    /** Present only when more pages remain */
+    cursor?: string;
+}
 /**
  * KV key entry
  */
@@ -3024,6 +3489,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -3035,6 +3513,13 @@ interface PlaycademyConfig {
     description?: string;
     /** Game emoji icon */
     emoji?: string;
+    /**
+     * Browser permissions to request for the game's iframe (e.g.
+     * `['microphone']`). Opt-in per game; only `microphone` and `camera` are
+     * delegated this way. Fullscreen, autoplay, and gamepad are granted to
+     * every game automatically.
+     */
+    permissions?: GamePermission[];
     /** Build command to run before deployment */
     buildCommand?: string[];
     /** Path to build output */
@@ -3049,6 +3534,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -3363,6 +3850,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             };
             bucket: {
                 list: (slug: string, prefix?: string) => Promise<BucketFile[]>;
+                listPage: (slug: string, options?: BucketListPageOptions) => Promise<BucketFilePage>;
                 get: (slug: string, key: string) => Promise<ArrayBuffer>;
                 put: (slug: string, key: string, content: Blob | ArrayBuffer | Uint8Array, contentType?: string) => Promise<void>;
                 initiateUpload: (slug: string, key: string, contentType: string) => Promise<{
@@ -3534,10 +4022,13 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             create: (gameId: string, courseId: string, data: {
                 title: string;
                 purpose: _playcademy_types.AssessmentPurpose;
+                standard?: _playcademy_types.AssessmentStandardRef;
             }) => Promise<_playcademy_types.AssessmentRow>;
+            attachExisting: (gameId: string, courseId: string, manifest: _playcademy_types.AssessmentAssociationImportManifest) => Promise<_playcademy_types.AssessmentAssociationImportResponse>;
             update: (gameId: string, courseId: string, testIdentifier: string, data: {
                 title?: string;
                 purpose?: _playcademy_types.AssessmentPurpose;
+                standard?: _playcademy_types.AssessmentStandardRef;
                 status?: _playcademy_types.AssessmentStatus;
             }) => Promise<_playcademy_types.AssessmentRow>;
             reorder: (gameId: string, courseId: string, purpose: _playcademy_types.AssessmentPurpose, testIdentifiers: string[]) => Promise<{
@@ -3547,7 +4038,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 action: 'discarded' | 'archived';
             }>;
             listTestLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<_playcademy_types.QtiAssessmentTestListResponse>;
-            copy: (gameId: string, courseId: string, testIdentifier: string, purpose: _playcademy_types.AssessmentPurpose) => Promise<_playcademy_types.AssessmentRow>;
+            copy: (gameId: string, courseId: string, testIdentifier: string, purpose: _playcademy_types.AssessmentPurpose, standard?: _playcademy_types.AssessmentStandardRef) => Promise<_playcademy_types.AssessmentRow>;
             listQuestions: (gameId: string, courseId: string, testIdentifier: string) => Promise<_playcademy_types.QtiTestQuestionsResponse>;
             listQuestionLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<_playcademy_types.QtiAssessmentItemListResponse>;
             createQuestion: (gameId: string, courseId: string, testIdentifier: string, data: _playcademy_types.QtiQuestionCreateInput) => Promise<_playcademy_types.QtiTestQuestionRef>;
@@ -3574,5 +4065,54 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
     };
 }
 
-export { ApiError, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, ErrorResponseBody, 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, MessageEventMap, 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 };
+/**
+ * @fileoverview Platform INIT Handshake
+ *
+ * The sender half of the INIT handshake between an embedding window (the
+ * hub, or a parent game via `client.embed`) and a game iframe. INIT is
+ * resent on an interval until the game answers READY, which absorbs the
+ * race where the iframe isn't listening yet when the first INIT lands.
+ *
+ * The receiver half lives in `core/static/init.ts` (`PlaycademyClient.init()`).
+ * The three timing constants below describe both halves, so their invariant
+ * is checkable in one place.
+ */
+
+/** How long a game's `init()` waits for INIT before giving up. */
+declare const INIT_WAIT_TIMEOUT_MS = 25000;
+/** How often the embedding window resends INIT until READY arrives. */
+declare const HANDSHAKE_RESEND_INTERVAL_MS = 300;
+/**
+ * When the embedding window stops resending and declares the load failed.
+ * Must exceed {@link INIT_WAIT_TIMEOUT_MS} so a struggling game gets to
+ * send INIT_ERROR before the embedder gives up.
+ */
+declare const HANDSHAKE_MAX_DURATION_MS = 30000;
+interface BeginInitHandshakeOptions {
+    /** The game iframe (needs `contentWindow` for postMessage). */
+    iframe: HTMLIFrameElement;
+    /** Target origin for postMessage security. */
+    origin: string;
+    /** The INIT payload to send. */
+    payload: GameContextPayload;
+    /** Called once if the game never answers READY within the max duration. */
+    onTimeout: () => void;
+    /**
+     * Called once if INIT cannot be posted at all (an unclonable payload
+     * throws identically on every resend, so retrying cannot succeed).
+     * The handshake is already stopped when this fires.
+     */
+    onSendError?: (error: unknown) => void;
+}
+/**
+ * Sends INIT immediately, then resends every
+ * {@link HANDSHAKE_RESEND_INTERVAL_MS} until stopped. The caller stops the
+ * handshake when READY arrives; after {@link HANDSHAKE_MAX_DURATION_MS}
+ * without a stop, `onTimeout` fires once (already stopped).
+ *
+ * @returns A `stop` function that clears the resend interval and the timeout.
+ */
+declare function beginInitHandshake({ iframe, origin, payload, onTimeout, onSendError }: BeginInitHandshakeOptions): () => void;
+
+export { ApiError, HANDSHAKE_MAX_DURATION_MS, HANDSHAKE_RESEND_INTERVAL_MS, INIT_WAIT_TIMEOUT_MS, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, beginInitHandshake, extractApiErrorInfo, isTrustedIframeMessage, messaging };
+export type { ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, 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, MessageEventMap, 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 };