@playcademy/sdk 0.16.1-beta.1 → 0.16.1-beta.10

package/README.md

@@ -139,9 +139,10 @@ const completed = await client.timeback.assessments.submit(attempt.attemptId, {
 })
 ```
 
-`start()` resumes an unfinished attempt or selects the next live test. Save payloads are
-question deltas, but each included question replaces its complete response state; use `null` to
-clear an answer. Keep the returned `responseVersion` and send it with the next mutation.
+`start()` resumes a compatible unfinished attempt or selects content for a fixed test or standards
+review. Save payloads merge at both the item and response levels; omitted values remain unchanged,
+and `null` clears one response. Keep the returned `responseVersion` and send it with the next
+mutation.
 
 For local development, import the current ordered catalog before starting the dev host:
 
@@ -172,6 +173,46 @@ OAuth provider connections (Discord, Google, etc.).
 await client.identity.connect({ provider: 'discord' })
 ```
 
+### `client.embed`
+
+Launch other Playcademy games as embedded children (platform mode only). With `timeback`, the child's play time and completion are recorded on this game's Timeback course. Interrupted launches resume automatically when the child streams checkpoints; the `resume` option tunes or disables the persistence.
+
+```typescript
+const session = client.embed.launch({
+    slug: 'math-cakes',
+    container: overlayEl,
+    intent: { lessonId: 'two-digit-add', eLevel: 'E2' },
+    timeback: { activityId: 'two-digit-add-e2', grade: 2, subject: 'Math' },
+})
+
+const activity = await session.finished
+
+if (activity.status === 'completed') {
+    await activity.end({
+        correctQuestions: activity.correct,
+        totalQuestions: activity.total,
+        xpAwarded: 10,
+    })
+}
+
+await session.closed // iframe unmounted; dismiss surrounding UI
+```
+
+### `client.parent`
+
+The launch context when this game was launched by a parent game (`mode: 'child'`); `null` in every other mode. In child mode, activity reporting is relayed to the parent automatically, and `xpAwarded` becomes a suggestion the parent may override. Stream `client.parent.checkpoint(state)` to make interrupted launches resumable; the state comes back as `client.parent.resume`. Narrow with `isChildLaunched()` to get the relaxed types.
+
+```typescript
+import { isChildLaunched } from '@playcademy/sdk'
+
+if (isChildLaunched(client)) {
+    const { lessonId, eLevel } = client.parent.intent
+    startLesson(lessonId, eLevel)
+    // ...later: xpAwarded may be omitted; the parent decides the award
+    await client.timeback.endActivity({ correctQuestions, totalQuestions })
+}
+```
+
 ### `client.demo`
 
 Demo mode for anonymous players on the landing page.