@superbuilders/primer-tives 1.1.4 → 2.0.0

package/README.md

@@ -10,20 +10,18 @@ bun add @superbuilders/primer-tives
 
 ## Subpaths
 
-The package has **no root export**. Every symbol lives at exactly one subpath. Pick the subpath that owns the thing you need.
+Every symbol is exported from exactly one subpath. Import from the subpath that owns the thing you need.
 
 | Subpath | What it owns |
 |---|---|
 | `@superbuilders/primer-tives/server` | `createPrimerServer` and the four `PrimerServer` methods, the config and return types |
 | `@superbuilders/primer-tives/client` | `create` (browser SDK), the `PrimerState` discriminated union, every `*State` interface, the PCI render props |
 | `@superbuilders/primer-tives/contracts` | wire-shape types (`RendererInteraction`, `RendererSubmission`, `ContentInline`, PCI base types, review types), Zod schemas, the optional submission validator |
-| `@superbuilders/primer-tives/errors` | every error sentinel (`Err…`) — only home for them |
+| `@superbuilders/primer-tives/errors` | every error sentinel (`Err…`) |
 | `@superbuilders/primer-tives/logger` | the `PrimerLogger` interface, accepted by both server and client config |
 | `@superbuilders/primer-tives/grade-level` | `GradeLevel` type and the `GRADE_LEVELS` constant |
 | `@superbuilders/primer-tives/subject` | `Subject`, `SubjectScope`, the `SUBJECTS` constant |
 
-There is **no convenience re-export**. Importing `ErrInvalidSecretKey` from `/server` or `/client` will not work — it lives at `/errors` only. Same for `PrimerLogger` (`/logger`), grade level constants (`/grade-level`), subjects (`/subject`), and every wire-shape type (`/contracts`).
-
 ## End-to-end examples
 
 ### Native/manual student flow
@@ -157,6 +155,7 @@ const { studentId, accessToken, expiresInSeconds } = sessionResult.data
 ```ts
 import { create } from "@superbuilders/primer-tives/client"
 import type { PrimerState } from "@superbuilders/primer-tives/client"
+import * as logger from "@superbuilders/slog"
 
 const client = create({
   accessToken,
@@ -165,7 +164,8 @@ const client = create({
   supportedPcis: [
     "urn:primer:pci:division-remainder",
     "urn:primer:pci:fraction-addition"
-  ]
+  ],
+  logger
 })
 
 let state: PrimerState = await client.start()
@@ -173,7 +173,7 @@ let state: PrimerState = await client.start()
 while (state.phase !== "completed" && state.phase !== "fatal") {
   switch (state.phase) {
     case "observation":
-      renderStimulus(state.stimulus)
+      renderFrame(state.body, state.stimulus)
       state = await state.advance()
       break
     case "interaction":
@@ -252,7 +252,7 @@ Partial upsert of a native/manual student's placement-routing hints. Omitted fie
 const { gradeLevel } = await primer.setStudentHints(studentId, { gradeLevel: "3" })
 ```
 
-- Required for native/manual students before their first session — the first `/advance` call fails server-side without a `gradeLevel` on record.
+- Required for native/manual students before their first session. If the browser calls `/advance` without a `gradeLevel` on record, the server returns HTTP 412 `needs_hints` and the SDK surfaces it as `ErrNeedsHints` on a `fatal` state.
 - Safe to call repeatedly. Each call is a partial upsert.
 - Not needed for Timeback-linked students: `exchangeTimebackStudentForAccessToken` syncs the grade level from the authority on every call.
 - Throws `ErrStudentNotFound` if `studentId` is unknown; `ErrBadRequest` if the payload fails validation (e.g. unsupported `gradeLevel`).
@@ -347,7 +347,7 @@ interface Config<Pcis extends PciId = PciId> {
   readonly subject: SubjectScope
   readonly fetch?: typeof globalThis.fetch
   readonly abort?: AbortController
-  readonly logger?: PrimerLogger
+  readonly logger: PrimerLogger
 }
 
 interface Client<Pcis extends PciId = PciId> {
@@ -392,6 +392,7 @@ Every `InteractionState` shape also exposes `timeout(): Promise<PrimerState>`.
 ```ts
 interface FeedbackState extends NonSerializable {
   readonly phase: "feedback"
+  readonly body: ContentBlock[]
   readonly stimulus: RendererStimulus | null
   readonly interaction: RendererInteraction
   readonly submission: RendererSubmission
@@ -402,7 +403,13 @@ interface FeedbackState extends NonSerializable {
 }
 ```
 
-`RendererStimulus`, `RendererInteraction`, `RendererSubmission`, `ContentInline`, `InteractionReview` all come from `/contracts`.
+Every state that carries frame content (`ObservationState`, every `InteractionState` variant, `FeedbackState`) exposes the frame as three independent fields:
+
+- `body: ContentBlock[]` — the frame's prose, possibly empty.
+- `stimulus: RendererStimulus | null` — a discriminated union over media kinds (currently `{ kind: "image", alt, src }`).
+- `interaction: RendererInteraction | null` — the question, when present.
+
+`RendererStimulus`, `RendererInteraction`, `RendererSubmission`, `ContentBlock`, `ContentInline`, `InteractionReview` all come from `/contracts`.
 
 ### `ErroredState`
 
@@ -489,7 +496,6 @@ import type {
   PciSubmission,
   // stimulus shapes
   RendererStimulus,
-  BodyStimulus,
   ImageStimulus,
   // choice shapes
   RendererChoice,
@@ -609,6 +615,7 @@ import {
   ErrTokenExpired,
   ErrForbidden,
   ErrNotFound,
+  ErrNeedsHints,
   ErrUnsupportedPci,
   // /client thrown directly by `create()`
   ErrMalformedAccessToken,
@@ -654,6 +661,8 @@ import {
 | `ErrTokenExpired` | HTTP 401 with token-expired detail |
 | `ErrForbidden` | HTTP 403 |
 | `ErrNotFound` | HTTP 404 |
+| `ErrNeedsHints` | HTTP 412 — the student has no `gradeLevel` on record; backend must call `setStudentHints` and mint a fresh access token |
+| `ErrSdkUpgradeRequired` | the SDK's version is older than the server's minimum-supported version; bump `@superbuilders/primer-tives` to the latest |
 | `ErrUnsupportedPci` | HTTP 422 or a frame asks for a PCI not in `supportedPcis` |
 
 ## Thrown directly by `create()`
@@ -714,7 +723,7 @@ interface PrimerLogger {
 }
 ```
 
-Required by `PrimerServerConfig`, optional on `Config` (the client config). `@superbuilders/slog` matches this shape directly — `import * as logger from "@superbuilders/slog"` and pass `logger`.
+Required by both `PrimerServerConfig` and `Config` (the client config). The SDK never silently swallows operational events — every fatal, parse failure, transport error, and submission rejection goes through this logger. `@superbuilders/slog` matches this shape directly — `import * as logger from "@superbuilders/slog"` and pass `logger`.
 
 ---
 

package/dist/client/choice-state.d.ts

@@ -1,8 +1,9 @@
+import type { ContentBlock } from "../contracts/content";
 import type { SessionContext } from "./session-context";
 import type { PciId } from "../contracts/pci";
 import type { RendererChoice, RendererInteraction, RendererStimulus } from "../contracts/types";
 import type { PrimerState } from "./types";
-declare function choiceState<Pcis extends PciId>(ctx: SessionContext<Pcis>, stimulus: RendererStimulus | null, interaction: Extract<RendererInteraction<Pcis>, {
+declare function choiceState<Pcis extends PciId>(ctx: SessionContext<Pcis>, body: ContentBlock[], stimulus: RendererStimulus | null, interaction: Extract<RendererInteraction<Pcis>, {
     type: "choice";
 }>, options: RendererChoice[], maxChoices: number, minChoices: number): PrimerState<Pcis>;
 export { choiceState };

package/dist/client/choice-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"choice-state.d.ts","sourceRoot":"","sources":["../../src/client/choice-state.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EACX,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAG3E,iBAAS,WAAW,CAAC,IAAI,SAAS,KAAK,EACtC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EACnE,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAChB,WAAW,CAAC,IAAI,CAAC,CAqFnB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"choice-state.d.ts","sourceRoot":"","sources":["../../src/client/choice-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAA;AAOjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EACX,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAG3E,iBAAS,WAAW,CAAC,IAAI,SAAS,KAAK,EACtC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,IAAI,EAAE,YAAY,EAAE,EACpB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EACnE,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAChB,WAAW,CAAC,IAAI,CAAC,CAsFnB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/client/create.d.ts

@@ -9,7 +9,7 @@ interface Config<Pcis extends PciId = PciId> {
     readonly subject: SubjectScope;
     readonly fetch?: typeof globalThis.fetch;
     readonly abort?: AbortController;
-    readonly logger?: PrimerLogger;
+    readonly logger: PrimerLogger;
 }
 interface Client<Pcis extends PciId = PciId> {
     start(): Promise<PrimerState<Pcis>>;

package/dist/client/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/client/create.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAM3E,UAAU,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,KAAK;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,IAAI,EAAE,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAC9B;AAED,UAAU,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,KAAK;IAC1C,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;CACnC;AAUD,iBAAS,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CA4C5E;AAED,OAAO,EAAE,MAAM,EAAE,CAAA;AACjB,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/client/create.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAM3E,UAAU,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,KAAK;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,IAAI,EAAE,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAC7B;AAED,UAAU,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,KAAK;IAC1C,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;CACnC;AAUD,iBAAS,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CA2C5E;AAED,OAAO,EAAE,MAAM,EAAE,CAAA;AACjB,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA"}

package/dist/client/extended-text-state.d.ts

@@ -1,8 +1,9 @@
+import type { ContentBlock } from "../contracts/content";
 import type { SessionContext } from "./session-context";
 import type { PciId } from "../contracts/pci";
 import type { RendererStimulus, StandardRendererInteraction } from "../contracts/types";
 import type { PrimerState } from "./types";
-declare function extendedTextState<Pcis extends PciId>(ctx: SessionContext<Pcis>, stimulus: RendererStimulus | null, interaction: Extract<StandardRendererInteraction, {
+declare function extendedTextState<Pcis extends PciId>(ctx: SessionContext<Pcis>, body: ContentBlock[], stimulus: RendererStimulus | null, interaction: Extract<StandardRendererInteraction, {
     type: "extended-text";
 }>): PrimerState<Pcis>;
 export { extendedTextState };

package/dist/client/extended-text-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extended-text-state.d.ts","sourceRoot":"","sources":["../../src/client/extended-text-state.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EACX,gBAAgB,EAChB,2BAA2B,EAC3B,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAG3E,iBAAS,iBAAiB,CAAC,IAAI,SAAS,KAAK,EAC5C,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,2BAA2B,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,GAC1E,WAAW,CAAC,IAAI,CAAC,CAqKnB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"extended-text-state.d.ts","sourceRoot":"","sources":["../../src/client/extended-text-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAA;AAOjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EACX,gBAAgB,EAChB,2BAA2B,EAC3B,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAG3E,iBAAS,iBAAiB,CAAC,IAAI,SAAS,KAAK,EAC5C,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,IAAI,EAAE,YAAY,EAAE,EACpB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,2BAA2B,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,GAC1E,WAAW,CAAC,IAAI,CAAC,CAuKnB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/client/feedback-state.d.ts

@@ -1,9 +1,9 @@
-import type { ContentInline } from "../contracts/content";
+import type { ContentBlock, ContentInline } from "../contracts/content";
 import type { SessionContext } from "./session-context";
 import type { PciId } from "../contracts/pci";
 import type { RendererInteraction, RendererStimulus, RendererSubmission } from "../contracts/types";
 import type { InteractionReview } from "../contracts/review";
 import type { PrimerState } from "./types";
-declare function feedbackState<Pcis extends PciId>(ctx: SessionContext<Pcis>, stimulus: RendererStimulus | null, interaction: RendererInteraction<Pcis>, submission: RendererSubmission<Pcis>, isCorrect: boolean, feedbackContent: ContentInline[], review: InteractionReview<Pcis> | null): PrimerState<Pcis>;
+declare function feedbackState<Pcis extends PciId>(ctx: SessionContext<Pcis>, body: ContentBlock[], stimulus: RendererStimulus | null, interaction: RendererInteraction<Pcis>, submission: RendererSubmission<Pcis>, isCorrect: boolean, feedbackContent: ContentInline[], review: InteractionReview<Pcis> | null): PrimerState<Pcis>;
 export { feedbackState };
 //# sourceMappingURL=feedback-state.d.ts.map

package/dist/client/feedback-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feedback-state.d.ts","sourceRoot":"","sources":["../../src/client/feedback-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAA;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EACX,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAE3E,iBAAS,aAAa,CAAC,IAAI,SAAS,KAAK,EACxC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,mBAAmB,CAAC,IAAI,CAAC,EACtC,UAAU,EAAE,kBAAkB,CAAC,IAAI,CAAC,EACpC,SAAS,EAAE,OAAO,EAClB,eAAe,EAAE,aAAa,EAAE,EAChC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI,GACpC,WAAW,CAAC,IAAI,CAAC,CAmBnB;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}
+{"version":3,"file":"feedback-state.d.ts","sourceRoot":"","sources":["../../src/client/feedback-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAA;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EACX,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAE3E,iBAAS,aAAa,CAAC,IAAI,SAAS,KAAK,EACxC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,IAAI,EAAE,YAAY,EAAE,EACpB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,mBAAmB,CAAC,IAAI,CAAC,EACtC,UAAU,EAAE,kBAAkB,CAAC,IAAI,CAAC,EACpC,SAAS,EAAE,OAAO,EAClB,eAAe,EAAE,aAAa,EAAE,EAChC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI,GACpC,WAAW,CAAC,IAAI,CAAC,CAoBnB;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}