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

package/README.md

@@ -139,9 +139,24 @@ 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.
+
+The returned `flow` is authoritative and is derived from `purpose`; callers do not configure
+navigation, feedback, and submission independently:
+
+- `attempt-submit` is used for diagnostic and end-of-course attempts. Responses remain editable
+  through `save()` until `submit()` finalizes the whole attempt and returns feedback.
+- `item-submit` is used for review and mastery attempts. Submit each item in assessment order with
+  `submitItem()`. That operation atomically saves the item's responses, locks them, and returns safe
+  immediate feedback. Give each item request its own stable `submissionId` and reuse that ID for an
+  ambiguous retry; the returned canonical `itemSubmissions` ledger identifies committed items after
+  retry or resume.
+
+The host rejects `submitItem()` for attempt-submit flows, rejects `submit()` until every item-submit
+item is committed, and enforces `expectedResponseVersion` for every mutation.
 
 For local development, import the current ordered catalog before starting the dev host:
 
@@ -172,6 +187,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.