@playcademy/sdk 0.16.0 → 0.16.1-beta.10

package/README.md

@@ -116,6 +116,45 @@ await client.timeback.startActivity(
 )
 ```
 
+Hosted assessments use the same methods locally and when deployed:
+
+```typescript
+const attempt = await client.timeback.assessments.start({
+    activityId: 'math-diagnostic',
+    purpose: 'diagnostic',
+    subject: 'Math',
+    grade: 5,
+})
+
+const saved = await client.timeback.assessments.save(attempt.attemptId, {
+    expectedResponseVersion: attempt.responseVersion,
+    responses: {
+        [attempt.assessment.items[0].identifier]: { RESPONSE: 'A' },
+    },
+})
+
+const completed = await client.timeback.assessments.submit(attempt.attemptId, {
+    expectedResponseVersion: saved.responseVersion,
+    submissionId: crypto.randomUUID(),
+})
+```
+
+`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:
+
+```bash
+playcademy timeback assessments import
+playcademy dev
+```
+
+The host reads `.playcademy/timeback/assessment-fixtures.json` and keeps local attempts in memory.
+Restarting the dev host resets mutable attempt state. Deployed games use TimeBack automatically;
+game code never selects the provider or reads fixture content.
+
 ### `client.backend`
 
 HTTP client for game-specific backend functions deployed via `playcademy deploy`.
@@ -134,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.