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

package/README.md

@@ -139,9 +139,25 @@ 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, end-of-course, and mastery attempts. Responses remain
+  editable through `save()` until `submit()` finalizes the whole attempt and returns feedback.
+- `item-submit` is used for review attempts. Submit each administered item 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 an item-submit
+attempt has administered at least one item, and enforces `expectedResponseVersion` for every
+mutation.
 
 For local development, import the current ordered catalog before starting the dev host:
 
@@ -172,6 +188,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.

package/dist/contracts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The child-catalog contract: what a child game publishes about its
+ * deliverable lessons, per lesson id and level. A parent course authority
+ * resolves its lesson references against this document at compile time and
+ * fails closed at runtime on anything not `ready` in production.
+ *
+ * Ownership and flow: each child repo generates `.playcademy/catalog.json`
+ * from its own registry (`playcademy catalog generate`); a sync workflow
+ * carries copies into parent repos. Children never read the parent's
+ * compiled authority — this file and the launch payload are the entire
+ * surface between them.
+ *
+ * The document deliberately carries no app identity. The consuming repo
+ * assigns the namespace key (e.g. 'form', 'math-cakes') from sync
+ * provenance via its own repo → app map, so a child cannot misdeclare
+ * who it is and a typo cannot mint a phantom namespace.
+ */
+/** Contract identifier carried by every catalog document. */
+declare const CHILD_CATALOG_CONTRACT: 'playcademy-child-catalog-v1';
+/** The completion-evidence contract a catalog declares its runs report. */
+declare const CHILD_ATTEMPT_CONTRACT: 'playcademy-child-attempt-v1';
+/** Delivery levels a catalog may declare (serving-id dialect, lowercase). */
+declare const CATALOG_LEVELS: readonly ['e1', 'e2', 'e3', 'e4'];
+type CatalogLevel = (typeof CATALOG_LEVELS)[number];
+/**
+ * ready: real content. simulated: placeholder — playable for preview and
+ * simulation, never creditable in production. unavailable: intentionally
+ * absent at this level. Consumers must treat unknown values and missing
+ * levels as unavailable (fail closed).
+ */
+declare const CATALOG_READINESS: readonly ['ready', 'simulated', 'unavailable'];
+type CatalogReadiness = (typeof CATALOG_READINESS)[number];
+interface ChildCatalog {
+    /** The contract identifier. */
+    contract: typeof CHILD_CATALOG_CONTRACT;
+    /** The completion-evidence contract a catalog declares its runs report. */
+    evidence: typeof CHILD_ATTEMPT_CONTRACT;
+    /** The tool that generated this document (repo-relative path). */
+    generatedBy: string;
+    /** The in-repo source of truth the document was derived from. */
+    generatedFrom: string;
+    /** Lesson id → level → readiness. */
+    deliveries: Record<string, Partial<Record<CatalogLevel, CatalogReadiness>>>;
+}
+
+export { CATALOG_LEVELS, CATALOG_READINESS, CHILD_ATTEMPT_CONTRACT, CHILD_CATALOG_CONTRACT };
+export type { CatalogLevel, CatalogReadiness, ChildCatalog };

package/dist/contracts.js

@@ -0,0 +1,23 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/contracts/child-catalog.ts
+var CHILD_CATALOG_CONTRACT = "playcademy-child-catalog-v1";
+var CHILD_ATTEMPT_CONTRACT = "playcademy-child-attempt-v1";
+var CATALOG_LEVELS = ["e1", "e2", "e3", "e4"];
+var CATALOG_READINESS = ["ready", "simulated", "unavailable"];
+export {
+  CHILD_CATALOG_CONTRACT,
+  CHILD_ATTEMPT_CONTRACT,
+  CATALOG_READINESS,
+  CATALOG_LEVELS
+};